Lets AI agents preview, send, and track physical postcards through a real-world mailing service.
Also known as PostcardBot/mcp-server, @postcardbot/mcp-server
- Stars
- 5
- Tools
- 15
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 29, 2026
- License
- MIT
What is Postcard.bot MCP?
Postcard.bot lets AI agents preview, send, and track physical postcards through a real-world mailing service. It exposes 15 tools, such as preview_postcard, send_postcard, bulk_send.
Summary generated from the project's README
About Postcard.bot MCP server
Sending physical mail through an AI agent is possible with this local MCP server for Postcard.bot. Developers can use it to preview, send, and track postcards by connecting it to an MCP-compatible client using a Postcard.bot API key. The server operates via stdio and requires Node.js 20 or higher to run locally.
Users can manage individual mailings with the send_postcard tool or handle large distributions of up to 5,000 recipients using bulk_send. The server provides several read-only tools to check account balances, view current pricing, and monitor the status of specific postcard IDs or bulk jobs. It also allows for the management of webhooks to track delivery events like postcard.delivered or postcard.failed.
Before committing to a purchase, the preview_postcard tool lets you verify image dimensions, QR codes, and pricing without deducting any balance. Sending requires a prepaid account balance, and the server includes tools to check your current rates and lifetime top-up thresholds.
What you can do with it
- 1Verify postcard design and costCheck the price and visual layout of a postcard before spending any money.
- 2Execute large mailing campaignsSend a single design to a large list of recipients at once.
- 3Manage account fundsCheck your remaining prepaid balance and current per-card mailing rates.
Written from the project's README. Every use case is checked against a quote from it.
How to install Postcard.bot MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Postcard.bot MCP in Claude Code
$ claude mcp add mcp-server -- npx -y @postcardbot/mcp-serverInstall Postcard.bot MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@postcardbot/mcp-server"
]
}
}
}Install Postcard.bot MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@postcardbot/mcp-server"
]
}
}
}Install Postcard.bot MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@postcardbot/mcp-server"]}'Install Postcard.bot MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@postcardbot/mcp-server"
]
}
}
}Install Postcard.bot MCP in Codex
$ codex mcp add mcp-server -- npx -y @postcardbot/mcp-serverInstall Postcard.bot MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server] command = "npx" args = ["-y", "@postcardbot/mcp-server"]
Install Postcard.bot MCP in Gemini CLI
$ gemini mcp add -s user mcp-server npx -- -y @postcardbot/mcp-serverInstall Postcard.bot MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@postcardbot/mcp-server"
]
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Postcard.bot MCP tools 15
Detected from the READMEpreview_postcardsend_postcardbulk_sendcheck_balanceget_pricingcheck_statuslist_webhookscreate_webhookdelete_webhookmessageimage_urlimage_fit_mode
Show all 15 toolsShow fewer tools
back_templatepending_reviewsent
Configuration
POSTCARDBOT_API_KEY
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHub@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/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:
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
toandfrom:name,address_line1,city; optionaladdress_line2. Supplystateandzipfor US addresses.countrydefaults 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: optionalcover(crop to fill) orcontain(preserve with borders).back_template: optionalclassicorheritage.
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
processedcount 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
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
Postcard.bot MCP questions
How do I add Postcard.bot MCP to Claude Code?
Run claude mcp add mcp-server -- npx -y @postcardbot/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add Postcard.bot MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Postcard.bot MCP provide?
It exposes 15 tools, including preview_postcard, send_postcard, bulk_send, check_balance, get_pricing.