Send real postcards from code. MCP server for Postcard.bot — let AI agents send physical postcards worldwide.
Works with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible client.
The easiest way to get started — no API key needed, no local install. Just add the URL and sign in with your Postcard.bot account:
https://postcard.bot/api/mcpClaude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"postcardbot": {
"url": "https://postcard.bot/api/mcp"
}
}
}Claude Code:
claude mcp add --transport http postcardbot https://postcard.bot/api/mcpYour MCP client will open a browser for you to sign in with Google or email. Click "Allow" and you're ready to send postcards.
Related MCP server: SolMail MCP
If you prefer running the server locally with an API key:
Sign up at postcard.bot, go to your account page, and generate an API key.
Add credits at postcard.bot/buy-credits or via the API. Prepaid balance — volume pricing from $0.69/postcard.
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"postcardbot": {
"command": "npx",
"args": ["-y", "@postcardbot/mcp-server"],
"env": {
"POSTCARDBOT_API_KEY": "pk_live_your_key_here"
}
}
}
}Claude Code:
claude mcp add postcardbot -- npx -y @postcardbot/mcp-serverThen set the environment variable POSTCARDBOT_API_KEY in your shell.
Cursor / Windsurf — add the same JSON config to your MCP settings.
send_postcardSend a physical postcard. Cards are printed and shipped within 24 hours. Delivery takes 5-10 business days.
Parameters:
to — Recipient address (name, address_line1, city required; address_line2, state, zip, country optional)
from — Sender/return address (same fields)
message — Back-of-card message (max 350 characters)
image_url — Front image URL (publicly accessible, min 1875x1275px recommended)
Example prompt:
"Send a postcard to Jane Doe at 123 Main St, San Francisco CA 94102 with a photo of the Golden Gate Bridge and the message 'Wish you were here!'"
bulk_sendSend the same postcard to multiple recipients (async). Up to 5,000 recipients per request. Cards are processed in background batches.
Parameters:
recipients — Array of recipient addresses (max 5,000, same fields as to above)
from — Sender/return address (same for all postcards)
message — Back-of-card message (max 350 characters)
image_url — Front image URL (publicly accessible, min 1875x1275px recommended)
Returns a bulk_id immediately. Cards are processed in the background (~25/minute). Use check_status to poll progress.
Total cost is reserved upfront. Failed cards are automatically refunded.
check_balanceCheck account balance, lifetime top-up amount, and current volume pricing tier.
get_pricingGet all volume pricing tiers.
check_statusCheck delivery status of a previously sent postcard.
Parameters:
postcard_id — The ID returned from send_postcard
list_webhooksList all registered webhooks for your account.
create_webhookRegister a URL to receive postcard event notifications (sent, delivered, failed, returned). URL must use HTTPS. Max 10 webhooks per account.
Parameters:
url — HTTPS URL to receive webhook POST requests
events — Event types: postcard.created, postcard.sent, postcard.delivered, postcard.failed, postcard.returned
The signing secret is returned only once — save it securely. Events are signed with HMAC-SHA256 in the X-PostcardBot-Signature header.
delete_webhookDelete a registered webhook by its ID.
Parameters:
webhook_id — The webhook ID (wh_...)
You can also use the HTTP API directly without MCP:
curl -X POST https://postcard.bot/api/v1/postcards \
-H "Authorization: Bearer pk_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"to": {"name": "Jane Doe", "address_line1": "123 Main St", "city": "San Francisco", "state": "CA", "zip": "94102"},
"from": {"name": "John Smith", "address_line1": "456 Oak Ave", "city": "New York", "state": "NY", "zip": "10001"},
"message": "Wish you were here!",
"image_url": "https://example.com/photo.jpg"
}'Full API docs and OpenAPI spec: postcard.bot/developers
Variable | Required | Description |
| Yes | Your API key from postcard.bot/account |
| No | Override API base URL (default: https://postcard.bot) |
Volume pricing (based on lifetime top-up amount):
Tier | Lifetime top-up | USA | International |
Pay-as-you-go | $0 | $1.99 | $2.99 |
Starter | $1-$19 | $1.49 | $2.49 |
Bronze | $20-$49 | $1.29 | $2.29 |
Silver | $50-$199 | $0.99 | $1.99 |
Gold | $200-$499 | $0.85 | $1.85 |
Platinum | $500-$999 | $0.79 | $1.79 |
Diamond | $1,000+ | $0.69 | $1.69 |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| recipients | Yes | Array of recipient addresses (max 500) | |
| from | Yes | Sender (return) address — same for all postcards | |
| message | Yes | Message text for the back of every postcard (max 350 characters) | |
| image_url | Yes | URL of the image for the front of every postcard. Must be publicly accessible HTTPS URL. Recommended minimum resolution: 1875x1275 pixels. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: cost deduction upfront, automatic refunds for failed cards, volume pricing based on tier, and the 500-recipient limit. However, it doesn't mention authentication requirements, rate limits, or what happens if the balance is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise and well-structured: three sentences that each earn their place by covering purpose, constraints, and financial implications. It's front-loaded with the core functionality and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description does a good job covering the essential context: what the tool does, key constraints, and financial implications. However, it doesn't describe the return value or error conditions, which would be helpful given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by mentioning that recipients, message, image, and return address are the key components, but doesn't provide additional semantic context about parameter usage or constraints beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Send the same postcard to multiple recipients at once' with specific details about what remains constant (message, image, return address) and what varies (recipient addresses). It distinguishes from the sibling 'send_postcard' by emphasizing bulk functionality with a maximum of 500 recipients.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: for sending identical postcards to multiple recipients. It mentions the 500-recipient limit and volume pricing, but doesn't explicitly state when NOT to use it or name alternatives like 'send_postcard' for single recipients.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It describes what information is returned (balance, top-up amount, pricing tier) and the practical purpose (knowing costs and funds), but doesn't disclose behavioral traits like authentication requirements, rate limits, or whether this is a read-only operation. The description implies it's informational but doesn't explicitly state safety characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place. The first sentence states what the tool does, and the second provides clear usage guidance. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no annotations and no output schema, the description provides good contextual completeness. It explains what information is returned and when to use it. However, it doesn't describe the return format or structure, which would be helpful since there's no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, and instead focuses on the tool's purpose and usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('check account balance', 'lifetime top-up amount', 'current volume pricing tier') and resources ('account', 'funds', 'per-postcard cost'). It distinguishes from siblings by focusing on financial status rather than sending operations or status checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Use this before sending to know your per-postcard cost and available funds.' This provides clear context for usage versus alternatives like send_postcard or get_pricing, though it doesn't explicitly name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the delivery status of a previously sent postcard. Returns the current status, delivery tracking info, and expected delivery date.
| Name | Required | Description | Default |
|---|---|---|---|
| postcard_id | Yes | The postcard ID returned from send_postcard |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the return content (status, tracking info, delivery date) which is helpful, but doesn't mention error conditions, authentication needs, rate limits, or whether this is a read-only operation. It adds some behavioral context but leaves gaps for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose followed by return details. Zero wasted words, appropriately sized for a simple lookup tool. Every sentence earns its place by adding distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple tool with 1 parameter, 100% schema coverage, and no output schema, the description is reasonably complete. It explains what the tool does and what it returns. However, without annotations or output schema, it could benefit from more behavioral details (e.g., error cases).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single parameter. The description adds no additional parameter semantics beyond what's in the schema (e.g., format examples or constraints). Baseline 3 is appropriate when schema does all the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('check the delivery status'), the resource ('previously sent postcard'), and distinguishes it from siblings like send_postcard (which creates) and check_balance/get_pricing (which are unrelated). It uses precise verbs and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('previously sent postcard') and references send_postcard as the source of the ID, but doesn't explicitly state when NOT to use it or name alternatives. It provides clear context but lacks explicit exclusions or comparisons to siblings like bulk_send.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only operation by using 'Get', but doesn't explicitly state safety aspects like whether it's non-destructive or if it requires authentication. The inclusion of specific price examples adds some context, but key behavioral traits (e.g., rate limits, error handling) are missing, making it adequate but with gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and front-loaded, consisting of a single sentence that directly states the tool's purpose and includes key pricing details. Every word earns its place, with no redundant or vague language, making it efficient and easy to parse for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no output schema, no annotations), the description is reasonably complete for a simple pricing lookup. It explains what the tool returns (pricing tiers with examples) but lacks information on output format or error cases. With no structured fields to rely on, it meets minimum viability but could be more comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description adds value by explaining the pricing logic (based on lifetime top-up amount) and providing example price ranges for USA and International, which goes beyond the empty schema. This compensates well, though it's not a perfect 5 as it could include more details like currency or update frequency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving postcard pricing tiers based on lifetime top-up amount, with specific price examples for USA and International. It uses the verb 'Get' with the resource 'postcard pricing tiers', making the action and target explicit. However, it doesn't explicitly distinguish this from sibling tools like 'check_balance' or 'send_postcard', which prevents a score of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions pricing tiers but doesn't specify use cases, prerequisites, or comparisons to siblings like 'check_balance' (which might relate to costs) or 'send_postcard' (which might involve pricing). This lack of contextual usage information results in a low score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Recipient (mailing) address | |
| from | Yes | Sender (return) address | |
| message | Yes | Message text for the back of the postcard (max 350 characters) | |
| image_url | Yes | URL of the image for the front of the postcard. Must be a publicly accessible HTTPS URL. Recommended minimum resolution: 1875x1275 pixels. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: cost implications ('Price depends on volume tier... Charged from the user's prepaid Postcard.bot balance'), operational constraints ('printed and mailed to a real address'), and technical requirements ('publicly accessible HTTPS URL'). It doesn't mention delivery timeframes or error handling, keeping it from a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with core purpose, followed by cost, payment method, prerequisite, and requirements. Every sentence earns its place with zero waste, efficiently covering key aspects in a compact format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description does well by covering purpose, cost, payment, prerequisites, and key requirements. However, it lacks details on return values (e.g., confirmation ID, estimated delivery) and error cases, which would be helpful for a transactional tool with financial implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema: it mentions 'image URL (publicly accessible)' and 'message (max 350 characters)', which are already documented in the schema. No additional syntax or format details are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Send a physical postcard'), resource ('postcard'), and scope ('printed and mailed to a real address'). It distinguishes from siblings like 'bulk_send' by focusing on single sends, 'check_balance' by being a transactional tool, and 'check_status/get_pricing' by being an execution tool rather than informational.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('Use check_balance to see current pricing tier before sending') and provides clear prerequisites ('Requires an image URL... and a message...'). It also implies when not to use by specifying single-send context versus bulk operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Let AI agents prepare, review, pay for, and send real letters and postcards.
Physical mail API for AI agents. Send letters, certified mail. Sandbox + live keys via MCP.
Send e-cards to your human. The first store built for AI agents; free, no API key needed.
The agentic layer of letters. Agents send real printed mail worldwide, German compliance built in.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/PostcardBot/mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
