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

1. POSTCARDAI_API_KEY environment variable
2. ~/.postcardai/config.json (from CLI login)
3. 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

• Full Documentation
• MCP Guide
• API Reference

License

MIT