MCP Server

What PostcardBot/mcp-server does

PostcardBot/mcp-server exposes Postcard.bot mailing operations through the Model Context Protocol. An MCP-compatible client can preview a postcard, inspect pricing and account funding, place a single order, queue a bulk mailing, check processing results, and manage webhook endpoints.

The service supports physical postcards for US and international destinations. Messages can contain up to 350 characters, and postcard artwork is supplied as a publicly accessible HTTPS image URL. Single-card and bulk workflows accept sender and recipient address information, optional back templates, and image fitting options.

How it works

The local package runs as a Node.js process over MCP stdio. It communicates with Postcard.bot using an account API key and does not open a local HTTP port. A hosted alternative is available at https://postcard.bot/api/mcp for clients that support remote Streamable HTTP and OAuth; that deployment is separate from the npm package.

Use preview_postcard before sending to inspect price, balance sufficiency, image dimensions, QR-related checks, the back preview, and warnings. Previewing does not reserve funds, submit mail, or lock in a price. Sending requires prepaid account balance and an explicit call to a write-capable tool.

Bulk jobs accept 1–5,000 recipients, share artwork and sender details, and process asynchronously. {{name}} can be expanded to each recipient's first name. Funds are reserved up front, and review holds can delay printing. Status values distinguish review, printing acceptance, failure, and cancellation, but a sent result is not proof of delivery.

Setup and configuration

Node.js 20 or newer is required. Install the package through an MCP client's server configuration with npx and the @latest package tag, then provide POSTCARDBOT_API_KEY from a Postcard.bot account. Restart the client after changing its configuration or updating the package.

POSTCARDBOT_API_URL can override the default service origin of https://postcard.bot; changing this origin does not create a sandbox, so send tools may still create paid physical-mail orders. Keep the API key private. The wrapper does not automatically retry requests, so check order status before repeating a request that timed out.

Tools and capabilities

• preview_postcard: Validate artwork and postcard details, calculate pricing, check balance sufficiency, and return previews and warnings without sending.
• send_postcard: Place one paid postcard order; an order may enter pending_review.
• bulk_send: Queue up to 5,000 recipients with shared artwork, sender details, and message content.
• check_balance: Read account-specific rates, available balance, lifetime top-ups, and any pricing-protection expiry.
• get_pricing: Retrieve public pricing and subscription availability.
• check_status: Inspect a postcard or bulk job, including failure and refund information.
• list_webhooks, create_webhook, and delete_webhook: Manage account webhook endpoints. Created endpoints must use HTTPS, and the signing secret is returned only when the endpoint is registered.

Webhook events include postcard creation, sending, delivery, failure, and return. Receivers should verify the raw request body using the issued HMAC signature and make downstream actions idempotent.

Limitations and notes

Postcard previews do not reserve balance or pricing. Paid sends are non-idempotent, and a timeout may occur after an order has already been accepted. Delivery estimates are not guarantees. Bulk processed counts can include cards still waiting for review, and fulfillment routing is handled internally.

The standard MCP package does not automatically enable white-label designs or subscriptions. Current public prices should be read with get_pricing, while account-specific rates come from check_balance.