PostcardAI

You can connect your clients to the PostcardAI MCP Server to create, manage, and send postcard mailings through an MCP-compatible interface. This server exposes a set of tools for mailings, contacts, designs, lists, credits, brands and addresses, and account information, enabling you to perform end-to-end postcard workflows from your preferred MCP client.

How to use

To use the PostcardAI MCP Server with your MCP client, you run the local MCP server via the Node toolchain and configure your client to communicate with it. You have two common options: authenticate through the CLI and point your client to a local MCP server, or provide an API key and run the server with that key in the environment.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system. You will use npx to run the MCP server component and a browser-based login flow for authentication.

# 1) Install & Authenticate
npx @postcardai/cli login

# 2) Configure Claude Desktop (example step shown in the configuration)
# This step configures Claude to use the PostcardAI MCP server via the standard local MCP command
# You will place this JSON in the specified Claude desktop configuration location

If you prefer not to use browser authentication, you can supply an API key directly in your MCP client configuration. The server will read the API key as an environment variable when it starts.

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

How to install

Follow these concrete steps to set up the MCP server locally and connect your MCP client.

# prerequisites
node -v
npm -v

# 1. Install the MCP server tooling globally for local usage (via npx in practice)
# No permanent install is required; you can run the server via npx as shown in the quick start

# 2. Authenticate or set API key
npx @postcardai/cli login
# OR use API key in environment when starting the server in your MCP client config

2. Configure your MCP client to launch the server using the provided command. A typical local configuration uses npx to run the MCP server with automatic installation.

Configuration and usage notes

Environment variables shown in examples allow you to run the server without interactive login by supplying an API key. You can place the API key in your MCP client configuration under the appropriate env section.

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

Examples of typical prompts and workflows

Once configured, you can instruct your MCP client to perform common postcard tasks, such as creating mailings, managing contacts, designing visuals, and checking credits. Examples of actions you can perform include creating a mailing, listing mailings, generating a design from a prompt, or purchasing credits.

Security and credentials

Use secure storage for credentials and prefer browser-based login when first configuring. If you choose API key authentication, guard the key and rotate it as needed.

Troubleshooting tips

If you encounter connection issues, verify that the MCP server process is running and that your client is configured to communicate with the correct local command and arguments. Check that the environment variable for the API key (if used) is correctly set in your client configuration.

Available tools

create_mailing

Create a new mailing and prepare it for sending in a campaign.

list_mailings

List mailings with filters such as status, date, and recipient counts.

get_mailing

Retrieve detailed information about a specific mailing.

cancel_mailing

Cancel a mailing that has not yet been sent.

get_mailing_previews

Obtain preview images for a mailing before sending.

send_mailing

Confirm and send a mailing after reviewing previews.

get_mailing_analytics

Fetch delivery metrics and performance data for mailings.

create_contact

Create a new contact in your address book.

create_contacts_batch

Batch-create multiple contacts (up to 1000) in one operation.

match_contact

Find a contact by email, phone, or address.

list_contacts

List contacts with search and filtering options.

get_contact

Retrieve details for a specific contact.

update_contact

Update fields for an existing contact.

delete_contact

Remove a contact from your address book.

get_contact_history

Get mailing history for a contact.

create_design

Generate a design from a text prompt.

list_designs

List saved designs.

get_design

Get a design with its iterations.

iterate_design

Generate design variations.

publish_design

Publish a design iteration.

delete_design

Archive or delete a design.

create_list

Create a new contact list.

list_lists

List all contact lists.

get_list

Get details of a specific list.

update_list

Update a list's name or description.

delete_list

Delete a contact list.

add_contacts_to_list

Add contacts to a list.

remove_contacts_from_list

Remove contacts from a list.

get_credit_balance

Check your current credit balance.

estimate_mailing_cost

Estimate the cost of a mailing.

purchase_credits

Buy credits for sending mailings.

get_credit_transactions

View credit transaction history.

create_brand

Create a brand profile to use for mailings.

list_brands

List available brand profiles.

set_default_brand

Set the default brand for new mailings.

create_return_address

Add a return address for mailings.

set_default_return_address

Set the default return address.

get_account

View organization info, plan, and usage.