PostcardAI MCP Server

Model Context Protocol server for PostcardAI. Use PostcardAI with Claude, Cursor, and other AI assistants.

Quick Start

1. Install & Authenticate

npx @postcardai/cli login

This opens your browser to authenticate and stores credentials securely.

2. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "postcardai": {
      "command": "npx",
      "args": ["-y", "@postcardai/mcp-server"]
    }
  }
}

3. Restart Claude Desktop

That's it! Ask Claude to send postcards.

Alternative: API Key

If you prefer not to use the CLI login:

{
  "mcpServers": {
    "postcardai": {
      "command": "npx",
      "args": ["-y", "@postcardai/mcp-server"],
      "env": {
        "POSTCARDAI_API_KEY": "pcai_sk_live_xxx"
      }
    }
  }
}

Get your API key from https://app.postcard.ai/settings/api

Available Tools

Mailings

Tool	Description
`create_mailing`	Create and send a postcard mailing
`list_mailings`	List mailings with filters
`get_mailing`	Get mailing details
`cancel_mailing`	Cancel a pending mailing
`get_mailing_previews`	Get preview images
`send_mailing`	Confirm and send after preview
`get_mailing_analytics`	Get delivery metrics

Contacts

Tool	Description
`create_contact`	Create a new contact
`create_contacts_batch`	Batch create (max 1000)
`match_contact`	Find by email/phone/address
`list_contacts`	List with search
`get_contact`	Get details
`update_contact`	Update fields
`delete_contact`	Remove contact
`get_contact_history`	Get mailing history

Designs

Tool	Description
`create_design`	Generate from prompt
`list_designs`	List saved designs
`get_design`	Get with iterations
`iterate_design`	Generate variations
`publish_design`	Publish iteration
`delete_design`	Archive design

Lists

Tool	Description
`create_list`	Create contact list
`list_lists`	List all lists
`get_list`	Get list details
`update_list`	Update name/description
`delete_list`	Delete list
`add_contacts_to_list`	Add contacts
`remove_contacts_from_list`	Remove contacts

Credits

Tool	Description
`get_credit_balance`	Check balance
`estimate_mailing_cost`	Estimate cost
`purchase_credits`	Buy credits
`get_credit_transactions`	Transaction history

Brands & Addresses

Tool	Description
`create_brand`	Create brand profile
`list_brands`	List brands
`set_default_brand`	Set default
`create_return_address`	Add return address
`set_default_return_address`	Set default

Account

Tool	Description
`get_account`	Organization info, plan, usage

Example Prompts

Once configured, try asking Claude:

"Send a postcard to John Smith at 123 Main St, Austin TX 78701 with a summer home buying theme"
"Show me my credit balance"
"Create a new contact list called 'VIP Clients'"
"Generate a thank you postcard design for new customers"

Configuration

Environment Variables

Variable	Required	Description
`POSTCARDAI_API_KEY`	No	API key (alternative to CLI login)
`POSTCARDAI_API_URL`	No	API URL (default: `https://api.postcard.ai/v1`)
`POSTCARDAI_CONFIG_PATH`	No	Custom config file path

Credential Priority

POSTCARDAI_API_KEY environment variable
~/.postcardai/config.json (from CLI login)
Custom path via POSTCARDAI_CONFIG_PATH

Other Clients

Cursor

Add to Cursor settings under MCP:

{
  "postcardai": {
    "command": "npx",
    "args": ["-y", "@postcardai/mcp-server"]
  }
}

Claude Code

claude mcp add postcardai npx @postcardai/mcp-server

Documentation

License

MIT

postcardai-mcp