# PostcardAI MCP Server
[](https://www.npmjs.com/package/@postcardai/mcp-server)
[](https://opensource.org/licenses/MIT)
[Model Context Protocol](https://modelcontextprotocol.io) server for PostcardAI. Use PostcardAI with Claude, Cursor, and other AI assistants.
## Quick Start
### 1. Install & Authenticate
```bash
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`:
```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:
```json
{
"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:
```json
{
"postcardai": {
"command": "npx",
"args": ["-y", "@postcardai/mcp-server"]
}
}
```
### Claude Code
```bash
claude mcp add postcardai npx @postcardai/mcp-server
```
## Documentation
- [Full Documentation](https://docs.postcard.ai)
- [MCP Guide](https://docs.postcard.ai/ai-tools/mcp-server)
- [API Reference](https://docs.postcard.ai/api-reference)
## License
MIT
