MCP Server README

@postcardbot/mcp-server

A local MCP server for Postcard.bot. Preview, send and track physical postcards from an MCP-compatible client, using your Postcard.bot API key.

Install and connect

Requires Node.js 20+. Get a key in your account. You can preview before funding; sending requires prepaid balance.

For clients that use an mcpServers configuration:

config.json

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

Keep the real key private. Restart the MCP client after changing configuration or updating the package. Pin @postcardbot/mcp-server@1.3.0 for a reproducible version, or use @latest to follow new releases. The server uses stdio; it is not an HTTP server and does not open a local listening port.

Environment variable	Required	Purpose
`POSTCARDBOT_API_KEY`	Yes	API key from your account
`POSTCARDBOT_API_URL`	No	Server origin override; defaults to `https://postcard.bot`

An origin override is not a sandbox switch. send_postcard and bulk_send create paid physical-mail orders. The wrapper does not automatically retry requests: a timed-out send may already have been accepted, so check before repeating it.

Hosted alternative

For a client supporting remote Streamable HTTP and OAuth, use its remote-server setup with:

text

https://postcard.bot/api/mcp

Follow the client's sign-in flow. This hosted service is deployed separately; its advertised tool list may differ from the local npm package documented below. Do not put a remote URL into a client's local stdio configuration.

Tools in 1.3.0

Tool	Behavior
`preview_postcard`	Price, balance sufficiency, image/QR checks, back preview and warnings; no mail or balance deduction
`send_postcard`	Place one paid order; may return `pending_review`
`bulk_send`	Queue 1–5,000 recipients with shared artwork and sender
`check_balance`	Read actual account prices, balance, lifetime top-ups and any protection expiry
`get_pricing`	Read current public pricing and subscription availability
`check_status`	Read postcard or bulk-job status, including failure/refund information
`list_webhooks`	List the account's webhook endpoints
`create_webhook`	Register an HTTPS endpoint; returns its signing secret once
`delete_webhook`	Remove a webhook by ID

Read-only tools are annotated as such. Paid sends are marked non-idempotent and write-capable so clients can distinguish them from previews.

Preview and single-card inputs

to and from: name, address_line1, city; optional address_line2. Supply state and zip for US addresses. country defaults to US; use two-letter codes.
message: up to 350 characters.
image_url: a publicly accessible HTTPS image URL. Preview checks the image dimensions and fit for the destination.
image_fit_mode: optional cover (crop to fill) or contain (preserve with borders).
back_template: optional classic or heritage.

Start with a prompt such as:

Preview a postcard using this photo, sender, recipient and message. Show me the price and any warnings, but do not send it yet.

A preview does not reserve a price or balance. Call check_balance for current account rates and explicitly request a send when ready.

Bulk and delivery status

bulk_send accepts recipients, from, message, image_url, and optional back_template. {{name}} expands to the recipient's first name. Cost is reserved upfront and processing is asynchronous; review holds can delay printing.

Pass either the postcard ID or bulk_id in check_status.postcard_id:

config.json

{"postcard_id": "bulk_example"}

pending_review: paid and queued; not yet submitted for printing.
sent: accepted for printing; not proof of delivery.
failed / cancelled: check the returned reason and refund information.
A bulk job's processed count may include cards still under review.

Delivery estimates are not guarantees. Fulfilment routing is internal; no supplier field is required or displayed by the package.

Webhooks

create_webhook takes url and an events array. Supported event names are postcard.created, postcard.sent, postcard.delivered, postcard.failed, and postcard.returned. Save the returned secret securely.

Verify the raw body against X-PostcardBot-Signature: t=UNIX_SECONDS,v1=BASE64_HMAC_SHA256, signing timestamp.rawBody with the issued secret. Preserve Base64 padding. Payloads have an event, timestamp, and data envelope; postcard fields are inside data. Bulk summaries use data.is_bulk and data.bulk_id. Make receiver-side business actions idempotent.

Node, Python and cURL examples include tested webhook receivers.

Pricing

USD per postcard, including printing and postage. Snapshot: October 28, 2026. Use get_pricing for live public rates and check_balance for account-specific rates.

Option	Lifetime paid top-ups	US	International
Pay as you go	None	$2.99	$2.99
Prepaid	$5+	$1.99	$2.79
Prepaid	$50+	$1.69	$2.69
Prepaid	$500+	$1.49	$2.49

Minimum top-up is $5. These are cumulative funding thresholds, not card counts. Balance and lifetime progress do not expire; per-card rates may change. Eligible existing funded accounts keep previous rates through December 31, 2026 Pacific. check_balance reports the actual rate and pricing_protected_until where applicable.

White-label early access

White-label plans are announced, with free early-access requests. Paid subscriptions are not open yet. Standard MCP sending does not automatically enable custom white-label designs.

Planned plan	Subscription	US/card	International/card
Business	$99/month	$0.99	$2.19
Pro monthly	$199/month	$0.89	$2.09
Pro yearly	$1,999/year	$0.89	$2.09

Cards are charged separately from subscription fees.

Development

Terminal

npm ci
npm test
npm pack

Tests use a local mock API and real MCP stdio transport; no real key, payment or physical mail is needed. prepack rebuilds the distributable so the npm artifact matches the TypeScript source. Version information is read from package.json.

License

MIT