Based on the provided schema, this server lets you send and track physical postcards via Postcard.bot and check pricing/balance.
Send a single paid physical postcard with recipient/sender addresses, a ≤350-character message, and a public HTTPS image URL.
Bulk-send the same postcard to up to 500 recipients.
Check account balance, lifetime top-ups, and current volume pricing tier.
Retrieve current postcard pricing tiers.
Check the status of a previously sent postcard by ID.
A local MCP server for Postcard.bot. Preview, send and track physical postcards from an MCP-compatible client, using your Postcard.bot API key.
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/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 |
| Yes | API key from your account |
| No | Server origin override; defaults to |
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.
For a client supporting remote Streamable HTTP and OAuth, use its remote-server setup with:
https://postcard.bot/api/mcpFollow 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.
Related MCP server: SolMail MCP
Tool | Behavior |
| Price, balance sufficiency, image/QR checks, back preview and warnings; no mail or balance deduction |
| Place one paid order; may return |
| Queue 1–5,000 recipients with shared artwork and sender |
| Read actual account prices, balance, lifetime top-ups and any protection expiry |
| Read current public pricing and subscription availability |
| Read postcard or bulk-job status, including failure/refund information |
| List the account's webhook endpoints |
| Register an HTTPS endpoint; returns its signing secret once |
| 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.
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_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.
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.
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 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.
npm ci
npm test
npm packTests 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.
MIT
Send the same postcard to multiple recipients at once. Same message, image, and return address for all cards — only the recipient addresses differ. Maximum 500 recipients per request. Total cost is deducted upfront from balance; failed cards are automatically refunded. Volume pricing applies based on your tier.
Inputs: recipients (required), from (required), message (required), image_url (required).
Check account balance, lifetime top-up amount, and current volume pricing tier. Use this before sending to know your per-postcard cost and available funds.
Inputs: no named parameters.
Check the delivery status of a previously sent postcard. Returns the current status, delivery tracking info, and expected delivery date.
Inputs: postcard_id (required).
Get postcard pricing tiers based on lifetime top-up amount. USA from $1.99 (<$50) down to $0.72 ($5000+), International from $2.99 down to $1.99.
Inputs: no named parameters.
Send a physical postcard that will be printed and mailed to a real address. Price depends on volume tier based on lifetime top-up (from $0.72–$1.99 USA, $1.99–$2.99 international). Charged from the user's prepaid Postcard.bot balance. Use check_balance to see current pricing tier before sending. Requires an image URL (publicly accessible) and a message (max 350 characters).
Inputs: to (required), from (required), message (required), image_url (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 5 tools
Each tool has a clearly distinct purpose with no overlap: bulk_send handles mass mailing, send_postcard for single cards, check_balance for account info, check_status for tracking, and get_pricing for cost details. The descriptions reinforce these boundaries, making misselection unlikely.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., bulk_send, check_balance, send_postcard). This uniformity makes the set predictable and easy for agents to understand and navigate.
With 5 tools, this server is well-scoped for its postcard-sending domain. Each tool serves a specific, essential function (sending, checking, pricing, status) without redundancy, making the count appropriate and manageable.
The tool surface provides complete coverage for the postcard-sending workflow: send_postcard and bulk_send for creation, check_status for tracking, check_balance for account management, and get_pricing for cost planning. There are no obvious gaps that would hinder agent operations.
Write, preview and mail real letters and postcards to US addresses from your AI app.
Send real handwritten postcards, letters, notecards and gift cards from your AI assistant, preview every piece and its price first, and track QR scan results.
Let AI agents prepare, review, pay for, and send real letters and postcards.
Send real paper letters from AI chat: print, envelope, postage, delivery. Pay per letter.
