Purpose
@postcardbot/mcp-server is the MCP (Model Context Protocol) server for Postcard.bot, used to let AI agents send real physical postcards. It is suitable for Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible client.
Key Capabilities
- Send a single postcard: Provide the recipient address (to), sender/return address (from), message on the back of the card (message, up to 350 characters), and front image URL (image_url, preferably publicly accessible, minimum 1875x1275px). The postcard is printed and mailed within 24 hours, and delivery takes 5-10 business days.
- Bulk send: Send the same postcard to multiple recipients (asynchronous). Up to 5000 recipients per request, and cards are processed in batches in the background (about 25 cards/minute). A bulk_id is returned immediately, and check_status can be used to poll progress. The total cost is reserved in advance, and failed cards are automatically refunded.
- Account and pricing queries: Query account balance, cumulative top-up amount, and current bulk pricing tier; get all bulk pricing tiers.
- Delivery status query: Query the delivery status of a sent postcard using the postcard_id returned by send_postcard.
- Webhook management: List all registered Webhooks for the account; register an HTTPS URL to receive postcard event notifications (postcard.created, postcard.sent, postcard.delivered, postcard.failed, postcard.returned), with a maximum of 10 Webhooks per account; the signing secret is returned only once, and events are signed using HMAC-SHA256 in the X-PostcardBot-Signature header; registered Webhooks can be deleted by webhook_id (wh_...).
How to Use
Hosted server (recommended)
No API key required, no local installation required. Just add the URL and sign in with a Postcard.bot account. In Claude Desktop's configuration file (~/Library/Application Support/Claude/claude_desktop_config.json), add the configuration. The MCP client will open a browser, letting you sign in with Google or email, and click "Allow" to start sending postcards.
Local server (npm)
- Get an API key: register at postcard.bot and go to the account page to generate an API key.
- Add credits at postcard.bot/buy-credits or via the API. It uses prepaid balance, with bulk pricing starting at $0.69/card.
- Configure the MCP client and set the POSTCARDBOT_API_KEY environment variable in the shell. For Cursor / Windsurf, add the same JSON configuration in the MCP settings.
Use the HTTP API directly
The HTTP API can also be used directly without MCP. See postcard.bot/developers for the full API documentation and OpenAPI specification.
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!'"
Use Cases
Suitable for personal or business scenarios that need to send physical postcards through AI agents, such as marketing outreach, customer care, event invitations, etc., supporting both single and large-scale bulk sending.
Limitations
- Messages are limited to 350 characters.
- Front images must be publicly accessible, with a recommended minimum of 1875x1275px.
- Bulk sending supports up to 5000 recipients per request, with background processing speed of about 25 cards/minute.
- Webhooks must use HTTPS, with a maximum of 10 per account.
- It uses prepaid balance, with bulk pricing starting at $0.69/card (based on cumulative top-up amount).
- Postcards are printed and mailed within 24 hours, and delivery takes 5-10 business days.
