PostGrid MCP Server

MCP server for PostGrid Print & Mail and Address Verification APIs. Send letters (standard, certified, certified with return receipt), mail MICR-encoded checks, manage contacts and templates, and verify US/Canadian addresses — all from Claude.

Tools (30)

Contacts

• postgrid_create_contact — Create a mailing contact

• postgrid_get_contact — Get contact details

• postgrid_list_contacts — List contacts with search and pagination

• postgrid_update_contact — Update contact fields

• postgrid_delete_contact — Delete a contact

Address Verification

• postgrid_verify_address — Verify and standardize an address (structured or freeform)

• postgrid_verify_addresses_batch — Verify up to 2,000 addresses at once

• postgrid_autocomplete_address — Autocomplete a partial address

• postgrid_lookup_city_state — Look up city/state from a ZIP code

Letters

• postgrid_create_letter — Send a letter (first class, standard, certified, or certified with return receipt)

• postgrid_get_letter — Get letter status and tracking

• postgrid_list_letters — List letters with search and pagination

• postgrid_cancel_letter — Cancel a letter before it prints

Bank Accounts

• postgrid_create_bank_account — Register a bank account for check payments

• postgrid_get_bank_account — Get bank account details (numbers masked)

• postgrid_list_bank_accounts — List bank accounts

• postgrid_delete_bank_account — Delete a bank account

Checks

• postgrid_create_cheque — Send a MICR-encoded check

• postgrid_get_cheque — Get check status

• postgrid_list_cheques — List checks with pagination

• postgrid_cancel_cheque — Cancel a check before it prints

Templates

• postgrid_create_template — Create an HTML template with Handlebars merge variables

• postgrid_get_template — Get template details and HTML content

• postgrid_list_templates — List templates

• postgrid_update_template — Update template HTML or description

• postgrid_delete_template — Delete a template

Utility

• postgrid_upload_pdf — Upload a PDF to temporary storage (Cloudflare R2) and get a URL for PostGrid

• postgrid_get_upload_url — Get a presigned PUT/GET URL pair for direct-to-R2 PDF upload (for Cowork/sandboxed environments)

• postgrid_estimate_cost — Estimate mailing cost without an API call

• postgrid_account_summary — Show API mode, connectivity, and rate table

Related MCP server: PostcardAI MCP Server

Setup

1. Get API Keys

Sign up at postgrid.com and get your API keys from the dashboard:

• Print & Mail API key — for contacts, letters, checks, templates

• Address Verification API key — for address verification tools

Both test and live keys are supported. Test keys start with test_ and live keys start with live_.

2. Install

git clone https://github.com/nathanieljones/postgrid-mcp-server.git
cd postgrid-mcp-server
npm install

3. Configure

Create a .env file (or set environment variables):

POSTGRID_PRINT_API_KEY=test_sk_...
POSTGRID_VERIFY_API_KEY=test_sk_...

For live keys, you must also set:

POSTGRID_CONFIRM_LIVE_MODE=true

This prevents accidental sends with real postage.

PDF upload (optional) — To use postgrid_upload_pdf, configure Cloudflare R2:

R2_ACCESS_KEY_ID=your_r2_access_key
R2_SECRET_ACCESS_KEY=your_r2_secret_key
R2_ENDPOINT=https://<account_id>.r2.cloudflarestorage.com
R2_BUCKET=postgrid-pdfs

Create an R2 bucket in your Cloudflare dashboard and add a lifecycle rule to auto-delete objects after 1 day.

4. Add to Claude

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "postgrid": {
      "command": "node",
      "args": ["/full/path/to/postgrid-mcp-server/dist/index.js"],
      "env": {
        "POSTGRID_PRINT_API_KEY": "test_sk_...",
        "POSTGRID_VERIFY_API_KEY": "test_sk_...",
        "R2_ACCESS_KEY_ID": "your_r2_access_key",
        "R2_SECRET_ACCESS_KEY": "your_r2_secret_key",
        "R2_ENDPOINT": "https://<account_id>.r2.cloudflarestorage.com",
        "R2_BUCKET": "postgrid-pdfs"
      }
    }
  }
}

Claude Desktop / Cowork (claude_desktop_config.json):

{
  "mcpServers": {
    "postgrid": {
      "command": "node",
      "args": ["/full/path/to/postgrid-mcp-server/dist/index.js"],
      "env": {
        "POSTGRID_PRINT_API_KEY": "test_sk_...",
        "POSTGRID_VERIFY_API_KEY": "test_sk_...",
        "R2_ACCESS_KEY_ID": "your_r2_access_key",
        "R2_SECRET_ACCESS_KEY": "your_r2_secret_key",
        "R2_ENDPOINT": "https://<account_id>.r2.cloudflarestorage.com",
        "R2_BUCKET": "postgrid-pdfs"
      }
    }
  }
}

Safety Features

Two-step confirmation — postgrid_create_letter and postgrid_create_cheque require two calls. The first returns a cost preview; the second (with confirmed: true) actually sends.

Live mode gate — Live API keys require POSTGRID_CONFIRM_LIVE_MODE=true in the environment. Without it, the server refuses to start with live keys.

Mode indicators — Every response is prefixed with [TEST] or [LIVE] so you always know which mode you're in.

Check safety thresholds — Checks over $10,000 show a warning. Checks over $100,000 are rejected.

Account number masking — Bank account and routing numbers are masked in all responses.

Idempotency — Create operations include unique idempotency keys so network retries don't produce duplicates.

Rate Table

Use postgrid_estimate_cost to calculate costs before sending.

License

MIT