# PostcardAI MCP Server

[![npm version](https://img.shields.io/npm/v/@postcardai/mcp-server.svg)](https://www.npmjs.com/package/@postcardai/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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