MCP 服务器

postcardbot-mcp-server

Send real physical postcards worldwide via AI agents. Supports single and bulk send (up to 500 recipients), balance checking, delivery tracking, and volume pricing from $0.72/card.

README

@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.

Quick Start

1. Get an API key

2. Add balance

Add credits at postcard.bot/buy-credits or via the API. Prepaid balance — volume pricing from $0.72/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 at once. Same message, image, and return address for all cards.

Parameters:

recipients — Array of recipient addresses (max 500, 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)

Example prompt:

"Send a holiday postcard to my 3 friends: Jane at 123 Main St SF CA, John at 456 Oak Ave NYC NY, and Bob at 789 Pine Rd Austin TX"

Total cost is deducted 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

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