Postals Mcp

Postals

The agent skill that turns any AI into a direct mail machine. One tool call. Real handwritten postcards. Delivered by USPS.

[npm version] [MCP compatible] [License]

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 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. You own 1–3 (any image pipeline works).

Full example

// Your pipeline produced://   - homeowner: { name, street, city, state, zip }//   - renderUrl: "https://cdn.mybucket.com/renders/123-oak-st-pool.jpg"
const msg = await generate_message({  recipient_context: `${homeowner.name}, homeowner at ${homeowner.street}. Corner lot with large flat backyard, no pool.`,  sender_context: "Blue Wave Pools — Austin, TX. Specializing in fiberglass pools installed in 14 days.",  tone: "warm",});
const result = await send_postcard({  to_name: homeowner.name,  to_address: homeowner.street,  to_city: homeowner.city,  to_state: homeowner.state,  to_zip: homeowner.zip,  message: msg.message,  front_image_url: renderUrl,  idempotency_key: `prospect-${homeowner.id}`,  // crucial for retries});
console.log(`Mailed card ${result.order_id}. ${result.cards_sent_today}/${result.daily_limit} today.`);

Why this works

• Real handwriting beats printed mail 5–10× on open rate
• Hyper-personalized image (their actual house!) makes it unignorable
• Warm, specific message feels human, not mass-mailed
• USPS delivery triggers the "this is important" instinct

Variations

All use the same two tool calls. Only the scanning, rendering, tone, and message change.

Message generation

You have three ways to compose the handwritten message. Pick based on your setup:

Option A — generate_message tool with Cloudflare AI

Set CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN. The server calls Llama 3.1 8B Instruct via Cloudflare Workers AI with Postals' proven tone profiles. Returns a ready-to-use message.

"env": {  "POSTALS_API_KEY": "...",  "CLOUDFLARE_ACCOUNT_ID": "...",  "CLOUDFLARE_API_TOKEN": "..."}

Option B — generate_message tool without AI (recommended for most agents)

Don't set the CF vars. The tool returns a structured prompt (system + user) that your agent uses with its own LLM. Since the calling agent is already an LLM (Claude, GPT, etc.), it generates a message at least as good as Llama 3.1 — often better.

Option C — compose_postcard_message MCP prompt

An MCP prompt primitive (not a tool). Claude Desktop surfaces this in the slash-command menu. The agent injects Postals' guidelines directly into its context and composes.

Option D — Your agent writes the message itself

Skip generate_message entirely. Your agent already knows how to write. Just pass a message directly to send_postcard.

Image handling

The front_image_url must be a public HTTPS URL to a PNG or JPEG. The server fetches the image, uploads it to our print partner and creates a custom card.

Recommended specs

• Format: PNG or JPEG
• Orientation: Landscape (wider than tall)
• Size: 2100 × 1500 px (7×5 inches at 300 DPI) — print quality
• Minimum: 1050 × 750 px
• Max file size: 10 MB
• Accessibility: Public URL, no auth headers, no signed URLs with short TTLs

Common sources

No image?

Set POSTALS_DEFAULT_CARD_IMAGE to your branded fallback. Every call without front_image_url uses the default. This is ideal for business use cases where every card shares the same template.

Test mode

Zero-cost, zero-risk testing. Set POSTALS_TEST_MODE=true in your env.

When enabled:

• All inputs are validated normally (state code, ZIP format, message length, HTTPS URL)
• Daily limit counter increments (so you can test spend controls)
• Rate limiter enforces 2-second delays (so you can test timing)
• The fulfillment API is not called — no cards printed, no money spent
• Response includes test_mode: true and mock_order_id

{  "success": true,  "test_mode": true,  "message": "Test mode — no card sent. Set POSTALS_TEST_MODE=false to send real cards.",  "mock_order_id": "test-1713099999999",  "recipient": "Jane Smith",  "estimated_delivery": "3-5 business days via USPS",  "cards_sent_today": 3,  "daily_limit": 25}

Best practice: start with POSTALS_TEST_MODE=true, verify your agent's tool calls look right, then flip it off for your first real send.

Spend control

Agents run autonomously. Bad config + no limits = expensive bug. This server ships with four safety layers:

1. Daily limit (POSTALS_DAILY_LIMIT, default 50)

Hard cap on cards per day. Counter resets at midnight UTC. Once reached:

isError: true"Daily limit reached (25/25). Resets at midnight UTC. Adjust with POSTALS_DAILY_LIMIT env var."

Set this low (5–10) while developing. Raise it once your agent is proven.

2. Rate limiter (2-second minimum between sends)

Firm server-side throttle. If you call send_postcard twice in rapid succession, the second call waits 2 seconds before executing. Prevents API abuse and gives you time to notice runaway behavior.

3. Idempotency keys

Pass idempotency_key in send_postcard args. Same key = same result, no duplicate send. Keys are cached for 24 hours.

await send_postcard({ ..., idempotency_key: "prospect-123-oak-st" });// If the network hiccups and your agent retries with the same key,// you get back the original response — no second card mailed.

Critical for autonomous agents. Without this, a network timeout + retry = two postcards.

4. Test mode

See above. Belt and suspenders during development.

Coming in v1.1

Prepaid wallet (pay ahead, spend down) with per-card billing, auto-reload with monthly cap, three funding paths (Stripe, USDC/WLD crypto, agent self-funding), instant pause (revoke API key from dashboard), and balance tracking in every response so agents can self-regulate.

Error handling

Errors return isError: true with an actionable message written for the agent to relay to the human. Examples:

Error messages are designed so your agent can read them and either self-correct or relay the fix to the human in plain language.

Configuration reference

All config is via environment variables in your MCP client config.

Per-call overrides: return_address, handwriting_style, and front_image_url in send_postcard args override the env defaults for that one send.

Handwriting styles

Default: Joyful Jennifer — warm, friendly, genuine handwriting.

Common handwriting style options:

• Joyful Jennifer — warm, friendly feminine
• Tarzan — bold, energetic
• Casual Craig — relaxed masculine
• Fancy Fiona — elegant script
• Precise Paul — neat, business-like

Pass the exact style name as handwriting_style in the tool args, or set POSTALS_HANDWRITING_STYLE globally. To see all styles available on your account, browse available styles at postals.ai/developers.

Troubleshooting

Claude Desktop doesn't show the tools

1. Fully quit Claude Desktop (menu → Quit, not just close window) and reopen. Config changes require a full restart.
2. Verify the config JSON is valid (no trailing commas, correct quotes).
3. On macOS, check the path: ~/Library/Application\ Support/Claude/claude_desktop_config.json.
4. Run npx -y postals-mcp manually in a terminal. If it errors, fix that first.

npx -y postals-mcp hangs

That's expected — it's waiting for MCP protocol input on stdin. To test it standalone, use the included test harness:

cd src/MCP/postals-mcpnpm installnpm run buildPOSTALS_API_KEY=test POSTALS_TEST_MODE=true node test-harness.mjs

"POSTALS_API_KEY not set"

The env var isn't being passed to the server. Check that:

• Your MCP client config has the env block set correctly
• You restarted the client after editing config
• The key is wrapped in quotes in JSON

"Cannot fetch image from URL"

The image URL must be:

• A public HTTPS URL (no http://, no file://, no data:)
• Accessible without auth headers or cookies
• Returning a valid PNG or JPEG with Content-Type: image/png or image/jpeg

Test with curl -I <url> — should return 200 and a valid image content-type.

Cards aren't arriving

1. Is POSTALS_TEST_MODE set to true? If so, no cards are actually mailed. Remove it or set to false.
2. Check the order status at postals.ai/developers for the order_id returned by the call.
3. Delivery is 3–5 business days after the card is mailed (not ordered). Printing happens within 1 business day.

Rate limiter seems too slow

The 2-second minimum is intentional and firm. It prevents API abuse and gives you a chance to notice runaway behavior.

FAQ

How much does it cost? $4.99 per card. No monthly minimums, no subscriptions. Volume discounts starting at 101 cards/month (v1.1).

How fast does it arrive? 3–5 business days via USPS after mailing. Cards are printed and mailed within 1 business day of the API call.

Is the handwriting really handwritten? Yes. Custom-built robots hold real pens and write in real ink on real paper. Recipients can't tell it's robotic.

What's the open rate on handwritten mail? Typically 5–10× higher than printed direct mail. Personalized imagery on the front (AI-rendered) further lifts response rates.

What countries are supported? US addresses ship for $4.99/card with 3-5 business day USPS delivery. International addresses are supported — delivery takes longer and pricing varies by destination. Contact us for international rates.

Can I send letters or packages? Postcards only in v1.0. Letters, envelopes, and greeting cards planned for later releases.

What image formats work? PNG or JPEG. Landscape 7×5 inches (2100×1500 px at 300 DPI) is ideal.

Can I cancel a send? Not in v1.0. Cancel-within-printing-window (cancel_postcard tool) is planned for v1.1.

Can I check delivery status? Not in v1.0. check_order_status tool is planned for v1.1.

What happens if the agent has a bug and tries to send 1000 cards? Set POSTALS_DAILY_LIMIT low (5–10) while developing. Send #11 returns an error instead of mailing. Combined with idempotency_key for retries and 2-second rate limiting, the three most common runaway scenarios are covered. v1.1 adds a wallet with a hard balance cap — once you hit $0, the agent stops.

Can the agent fund itself from crypto earnings? Coming in v1.1. Three funding paths: Stripe (human pays), crypto deposit (human sends USDC/WLD), and agent self-funding (agent spends from its own wallet — human-authorized with monthly cap). This enables fully autonomous business loops: agent earns crypto → funds wallet → sends cards → closes deals → earns more.

Can I use this commercially? Yes. MIT license. Cards are billed per-send, no license fees.

How does pricing compare to Lob or PostGrid? Lob and PostGrid do printed postcards at $0.48–$0.77. We do handwritten postcards at $4.99. Different product. The handwriting premium pays for itself via the dramatically higher open and response rates for the kinds of outbound use cases where this matters (real estate, home services, high-ticket sales).

Can multiple agents share one API key? Yes, but they share the daily limit. Use separate keys per agent for isolation (v1.1+ supports multiple keys per account).

Does this work with langchain / crewai / autogen? Any framework with MCP client support works. The TypeScript/Python MCP SDK connects to this server like any other MCP tool. See the Custom agents section for code.

What data do you log? Structured JSON events to stderr only. We log: event name, timestamp, city/state (for debugging), counter values, order IDs. We never log: full addresses, full messages, recipient names, API keys, or image URLs with auth tokens.

What's next

Current: v1.0 — $4.99/card.

Coming in v1.1 (2–3 weeks):

• Postals developer signup at postals.ai/developers
• Prepaid wallet (pay ahead, spend down) with Stripe + USDC crypto
• check_balance tool — agents see their balance in every response
• check_order_status tool — poll fulfillment status
• cancel_postcard tool — cancel within printing window
• No external account required

Coming in v2.0 (6–8 weeks):

• Full developer dashboard at postals.ai/developers
• Auto-reload with monthly cap
• Webhook events (card_sent, low_balance, daily_limit_hit)
• Multiple API keys per account
• Path 3: Agent self-funding from its own crypto wallet (human-authorized)
• USPS CASS-certified address validation
• Volume pricing tiers (101–500: $4.49, 501–2000: $3.99, 2000+: custom)

Coming in v3.0+:

• generate_card_image tool — Recraft V3 AI card art
• Card template library (thank-you, birthday, business, real estate, etc.)
• Multi-provider fulfillment (handwritten + printed options)
• International mail (Canada, UK, EU)
• Batch send tool for high-volume workflows
• Letters and envelopes

More on the roadmap and architecture at postals.ai.

Contributing

Issues and PRs welcome at the GitHub repo. For major changes, open an issue first to discuss.

Running the test harness:

npm installnpm run buildPOSTALS_API_KEY=test POSTALS_TEST_MODE=true node test-harness.mjs

All 37 checks should pass.

Links

• Website: postals.ai
• npm: postals-mcp
• GitHub: github.com/coopergwrenn/postals-mcp
• agents.md (for agents): postals.ai/agents.md
• SKILL.md (bundled skill file): ./SKILL.md
• Model Context Protocol: modelcontextprotocol.io

License

MIT © Postals