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:
**Claude Desktop** (~/Library/Application Support/Claude/claude_desktop_config.json):
**Claude Code:**
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):
**Claude Code:**
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