Postals MCP

Postals

The agent skill that turns any AI into a direct mail machine.

One tool call. Real handwritten postcards. Delivered by USPS.

Send physical handwritten postcards from any MCP-compatible AI agent — Claude Desktop, Cursor, Claude Code, OpenClaw, n8n, LangChain, CrewAI, or your own code. Postals handles image upload, card creation, robotic handwriting (real pen and ink), and USPS mailing.

Website: postals.ai

• 💌 $4.99 per card — no subscriptions, no monthly minimums
• ✍️ Real handwriting — robotic pens hold real ink (not font simulation)
• 📬 3–5 business days — printed and mailed via USPS
• 🤖 Built for agents — one tool call, spend controls, idempotency, test mode
• 🌎 US + international — worldwide delivery, pricing varies by destination

---

Table of Contents

• Why this exists
• Quick start (under 5 minutes)
• Client configuration
• Tools reference
• The pool builder workflow
• Message generation
• Image handling
• Test mode
• Spend control
• Error handling
• Configuration reference
• Handwriting styles
• Troubleshooting
• FAQ
• What's next (roadmap)
• Contributing
• License

---

Why this exists

A new pattern is emerging in the AI agent ecosystem: autonomous bots that scan the world (satellite imagery, social media, public records), identify opportunities, and reach out with real physical mail. Pool builders, landscapers, roofers, solar installers, real estate agents — they're closing five- and six-figure deals from postcards mailed by bots.

Before Postals, every builder hand-rolled their own mailing stack: image upload, card templating, print API, address validation, USPS handoff, tracking. It took weeks and was fragile.

We ship this as one tool. Your agent calls send_postcard with a recipient and a message. We do the rest.

---

Quick start

1. Sign up and get an API key

Coming soon — the developer portal at [postals.ai/developers](https://postals.ai/developers) is launching shortly. Once live, the flow is:

1. Go to postals.ai/developers

2. Create an account with your email (one-click magic link — no password)

3. Fund your wallet ($25 / $50 / $100 / $250 via Stripe or crypto)

4. Copy your postals_live_ API key

5. Paste it into your MCP config (see step 2 below)

That's it. No external accounts needed. Just Postals.

2. Add the server to your MCP client

Option A — ask your coding agent to install it (fastest path)

If you're in Claude Code, Cursor, Continue, Aider, or any other MCP client with filesystem access, just tell your agent:

Install the postals-mcp MCP server for this client. My Postals API key is: PASTE_YOUR_KEY_HERE. Start in test mode so I can verify the setup before sending real cards.

Your agent will locate your MCP config file, merge the postals entry into your existing mcpServers (preserving any other servers you have), wire up the env vars, and tell you to restart the client. You never touch JSON.

Optional — add return-address details to the same prompt so send_postcard works without per-call overrides:

...and use Jane Smith, 123 Main St, Austin TX 78701 as my return address.

Then fully quit and relaunch the client (Cmd+Q on macOS — just closing the window isn't enough).

Option B — edit your MCP config file directly

For Claude Desktop (no built-in filesystem access by default), or any client where you'd rather set it up manually, edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{

"mcpServers": { "postals": { "command": "npx", "args": ["-y", "postals-mcp"], "env": { "POSTALS_API_KEY": "your_api_key", "POSTALS_SENDER_NAME": "Jane Smith", "POSTALS_SENDER_ADDRESS": "123 Main St", "POSTALS_SENDER_CITY": "Austin", "POSTALS_SENDER_STATE": "TX", "POSTALS_SENDER_ZIP": "78701", "POSTALS_TEST_MODE": "true" } } } }

Configs for other clients (Cursor, Claude Code, OpenClaw) are in the Client configuration section below.

Fully restart the client after editing. (Not just close the window — quit from the menu.)

3. Verify it's working

Open a new chat and ask:

"List the MCP tools you have available."

You should see send_postcard and generate_message.

4. Send a test card

Still in test mode (POSTALS_TEST_MODE=true), ask:

"Send a postcard to Jane Smith at 123 Oak St, Austin TX 78701 saying 'Thanks for the great meeting yesterday — looking forward to next steps.'"

The agent will call send_postcard. You'll get back a mock order_id and confirmation that test mode is on. No card mailed, no money spent.

5. Go live

Remove POSTALS_TEST_MODE from your config (or set to false), restart, and your next send will mail a real card.

---

Client configuration

Copy-paste-ready configs for every major MCP client. If you're in Claude Code, Cursor, Continue, or Aider, you can skip this section entirely — just tell your agent to install Postals (see Option A in Quick Start) and it'll handle the config for you.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) %APPDATA%\Claude\claude_desktop_config.json (Windows)

{

"mcpServers": { "postals": { "command": "npx", "args": ["-y", "postals-mcp"], "env": { "POSTALS_API_KEY": "your_key" } } } }

Cursor

Global: ~/.cursor/mcp.json Per-project: .cursor/mcp.json in repo root

{

"mcpServers": { "postals": { "command": "npx", "args": ["-y", "postals-mcp"], "env": { "POSTALS_API_KEY": "your_key" } } } }

Claude Code

claude mcp add postals npx -y postals-mcp

Then set env vars in ~/.claude/settings.json under mcpServers.postals.env.

OpenClaw / InstaClaw

See the bundled SKILL.md for the full agent-facing skill definition. For standalone OpenClaw usage:

mcp_servers:

postals: command: npx args: ["-y", "postals-mcp"] env: POSTALS_API_KEY: ${POSTALS_API_KEY}

n8n (via Composio — v1.1+)

Install the Postals toolkit from the Composio marketplace. One-click add to any workflow. See Composio docs when available.

Custom agents (programmatic)

Any MCP client library works. Example with the official TypeScript SDK:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";

import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({ command: "npx", args: ["-y", "postals-mcp"], env: { POSTALS_API_KEY: "your_key", POSTALS_TEST_MODE: "true" }, }); const client = new Client({ name: "my-agent", version: "1.0" }, { capabilities: {} }); await client.connect(transport);

const result = await client.callTool({ name: "send_postcard", arguments: { to_name: "John Smith", to_address: "123 Oak St", to_city: "Austin", to_state: "TX", to_zip: "78701", message: "Hey John — thought you'd love this.", front_image_url: "https://example.com/render.png", idempotency_key: "john-smith-123-oak-001", }, });

---

Tools reference

send_postcard

Mails one physical handwritten postcard to a US address.

Input

Output (success)

{

"success": true, "order_id": 196937, "card_id": 305570, "recipient": "John Smith", "estimated_delivery": "3-5 business days via USPS", "balance_remaining": -1, "cards_available": -1, "cards_sent_today": 7, "daily_limit": 25 }

balance_remaining and cards_available return real values when using a postals_live_ API key from postals.ai/developers.

Output (test mode) adds test_mode: true and mock_order_id. No card is mailed.

Output (error) returns isError: true with an actionable message. See Error handling.

generate_message

AI-drafts a personalized postcard message. Uses Cloudflare AI if configured; otherwise returns a structured prompt your agent can use to self-generate (which is often just as good, since the agent is already an LLM).

Input

Output (AI configured)

{

"message": "Hey John — drove by your place on Oak St and couldn't help but picture how a pool would transform that backyard. Happy to share a quick render if you're curious. — Kevin, Blue Wave Pools", "char_count": 212, "tone": "warm", "ai_generated": true }

Output (AI not configured) — returns the system + user prompts your agent can feed into its own LLM:

{

"message": null, "ai_generated": false, "prompt": { "system": "You write short, personal messages for physical handwritten postcards...", "user": "Recipient: John Smith, homeowner at 123 Oak St...\nSender: Blue Wave Pools\n\nWrite the postcard message now." }, "instructions": "Cloudflare AI not configured. Use the system/user prompts above to generate the message...", "tone": "warm", "max_chars": 350 }

compose_postcard_message (MCP prompt)

An MCP prompt primitive (not a tool). Returns a formatted prompt template for your agent to use with its own LLM. Zero external API dependencies. Useful when you want deterministic, dependency-free message composition.

Arguments: recipient, sender (optional), tone (optional).

---

The pool builder workflow

This is the viral use case that put autonomous postcard sending on the map. Pool builders run agents that:

1. Scan satellite imagery of a neighborhood (Google Maps, Nearmap, etc.)
2. Classify — find homes without pools
3. Render — generate a personalized before/after showing a pool in that exact backyard
4. Compose — write a warm, specific message about that home
5. Send — mail the handwritten postcard
6. Close — five-figure deals landing weekly

Postals owns steps 4–5 with two tool calls.