# PostcardBot/mcp-server [Health: Active]

**Category:** 📦 Delivery  
**Repository:** https://github.com/PostcardBot/mcp-server  
**GitHub Stars:** 5  
**npm Downloads (last month):** 257  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/postcardbot-mcp-server

## Description
Send real physical postcards worldwide via AI agents. Bulk send up to 500 recipients. Volume pricing from $0.72/card.

## Tools
Capabilities this server exposes over MCP:

- **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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-server": {
    "command": "npx",
    "args": ["-y","@postcardbot/mcp-server@latest"],
    "env": {
      "POSTCARDBOT_API_KEY": "",
      "POSTCARDBOT_API_URL": ""
    }
  }
}
```

**Requires environment variables:** `POSTCARDBOT_API_KEY`, `POSTCARDBOT_API_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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`.

_Full upstream README: https://allmcps.com/mcp/postcardbot-mcp-server/readme_