@postcardbot/mcp-server

Send real postcards from code. MCP server for Postcard.bot — let AI agents send physical postcards worldwide.

Works with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible client.

Hosted Server (Recommended)

The easiest way to get started — no API key needed, no local install. Just add the URL and sign in with your Postcard.bot account:

https://postcard.bot/api/mcp

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "postcardbot": {
      "url": "https://postcard.bot/api/mcp"
    }
  }
}

Claude Code:

claude mcp add --transport http postcardbot https://postcard.bot/api/mcp

Your MCP client will open a browser for you to sign in with Google or email. Click "Allow" and you're ready to send postcards.

Local Server (npm)

If you prefer running the server locally with an API key:

1. Get an API key

Sign up at postcard.bot, go to your account page, and generate an API key.

2. Add balance

Add credits at postcard.bot/buy-credits or via the API. Prepaid balance — volume pricing from $0.69/postcard.

3. Configure your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "postcardbot": {
      "command": "npx",
      "args": ["-y", "@postcardbot/mcp-server"],
      "env": {
        "POSTCARDBOT_API_KEY": "pk_live_your_key_here"
      }
    }
  }
}

Claude Code:

claude mcp add postcardbot -- npx -y @postcardbot/mcp-server

Then set the environment variable POSTCARDBOT_API_KEY in your shell.

Cursor / Windsurf — add the same JSON config to your MCP settings.

Tools

send_postcard

Send a physical postcard. Cards are printed and shipped within 24 hours. Delivery takes 5-10 business days.

Parameters:

• to — Recipient address (name, address_line1, city required; address_line2, state, zip, country optional)

• from — Sender/return address (same fields)

• message — Back-of-card message (max 350 characters)

• image_url — Front image URL (publicly accessible, min 1875x1275px recommended)

Example prompt:

"Send a postcard to Jane Doe at 123 Main St, San Francisco CA 94102 with a photo of the Golden Gate Bridge and the message 'Wish you were here!'"

bulk_send

Send the same postcard to multiple recipients (async). Up to 5,000 recipients per request. Cards are processed in background batches.

Parameters:

• recipients — Array of recipient addresses (max 5,000, same fields as to above)

• from — Sender/return address (same for all postcards)

• message — Back-of-card message (max 350 characters)

• image_url — Front image URL (publicly accessible, min 1875x1275px recommended)

Returns a bulk_id immediately. Cards are processed in the background (~25/minute). Use check_status to poll progress.

Total cost is reserved upfront. Failed cards are automatically refunded.

check_balance

Check account balance, lifetime top-up amount, and current volume pricing tier.

get_pricing

Get all volume pricing tiers.

check_status

Check delivery status of a previously sent postcard.

Parameters:

• postcard_id — The ID returned from send_postcard

list_webhooks

List all registered webhooks for your account.

create_webhook

Register a URL to receive postcard event notifications (sent, delivered, failed, returned). URL must use HTTPS. Max 10 webhooks per account.

Parameters:

• url — HTTPS URL to receive webhook POST requests

• events — Event types: postcard.created, postcard.sent, postcard.delivered, postcard.failed, postcard.returned

The signing secret is returned only once — save it securely. Events are signed with HMAC-SHA256 in the X-PostcardBot-Signature header.

delete_webhook

Delete a registered webhook by its ID.

Parameters:

• webhook_id — The webhook ID (wh_...)

REST API

You can also use the HTTP API directly without MCP:

curl -X POST https://postcard.bot/api/v1/postcards \
  -H "Authorization: Bearer pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {"name": "Jane Doe", "address_line1": "123 Main St", "city": "San Francisco", "state": "CA", "zip": "94102"},
    "from": {"name": "John Smith", "address_line1": "456 Oak Ave", "city": "New York", "state": "NY", "zip": "10001"},
    "message": "Wish you were here!",
    "image_url": "https://example.com/photo.jpg"
  }'

Full API docs and OpenAPI spec: postcard.bot/developers

Environment Variables

Pricing

Volume pricing (based on lifetime top-up amount):

Links

• Postcard.bot

• Developer Docs

• OpenAPI Spec

• Buy Credits

• npm Package

License

MIT