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

{
  "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/[email protected] 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.

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:

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

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:

{"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.

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.

Cards are charged separately from subscription fees.

Development

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.

Links

• Developer docs
• OpenAPI
• API examples
• US artwork guide
• International artwork guide
• Source and issues
• Mailing terms

License

MIT