Metadata-Version: 2.5
Name: mailerbot-mcp
Version: 0.1.1
Summary: MCP server for the MailerBot direct mail API
Project-URL: Homepage, https://mailerbot.com
Project-URL: Documentation, https://mailerbot.com/docs/mcp
Project-URL: Repository, https://github.com/mailerbot-hq/MailerBot/tree/dev/mcp
Project-URL: Bug Tracker, https://github.com/mailerbot-hq/MailerBot/issues
Author-email: MailerBot <dev@mailerbot.com>
License: MIT
Keywords: ai,direct-mail,mailerbot,mcp,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mailerbot>=0.1.0
Requires-Dist: mcp[cli]<2,>=1.0
Description-Content-Type: text/markdown

# MailerBot MCP Server

MCP (Model Context Protocol) server for the MailerBot direct mail API. Enables AI tools like Claude, Cursor, and others to manage contacts, mailings, campaigns, and more.

## Remote server (recommended)

URL: `https://mcp.mailerbot.com/mcp`. OAuth is handled automatically — no API key to manage.

In Claude: **Settings > Connectors > Add custom connector**, then paste the URL above.

## Quick Start (Local / STDIO)

```bash
# Set your API key
export MAILERBOT_API_KEY="mb_live_..."

# Run via uvx
uvx mailerbot-mcp

# Or run from source
cd mcp
uv run mailerbot-mcp
```

### Claude Desktop Configuration

```json
{
  "mcpServers": {
    "mailerbot": {
      "command": "uvx",
      "args": ["mailerbot-mcp"],
      "env": {
        "MAILERBOT_API_KEY": "mb_live_..."
      }
    }
  }
}
```

## Self-Hosted (SSE)

```bash
docker build -t mailerbot-mcp -f mcp/Dockerfile .
docker run -p 8080:8080 \
  -e MAILERBOT_MCP_TRANSPORT=sse \
  -e MAILERBOT_BEARER_TOKEN="..." \
  mailerbot-mcp
```

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| `MAILERBOT_API_KEY` | API key for authentication | — |
| `MAILERBOT_BEARER_TOKEN` | OAuth bearer token (alternative to API key) | — |
| `MAILERBOT_API_URL` | API base URL | `https://api.mailerbot.com/api/v1` |
| `MAILERBOT_MCP_TRANSPORT` | Transport mode: `stdio` or `sse` | `stdio` |
| `MAILERBOT_MCP_HOST` | Host to bind (SSE mode) | `0.0.0.0` |
| `MAILERBOT_MCP_PORT` | Port to bind (SSE mode) | `8080` |

## Available Tools

**Contacts** — list, get, create, update, delete, validate addresses
**Contact Lists** — list, get, create, update, delete, add/remove contacts
**Documents** — list, get, create, update, delete
**Postcards** — list templates, list, get, create, delete
**Mailings** — list, get, create, update, delete, validate addresses, estimate cost, calculate cost, send
**Campaigns** — list, get, create, update, delete, add/remove mailings
**Dashboard** — stats, reporting
**Pricing** — catalog, countries, postage zones, postage rates
**Coupons** — list, get, create, update, delete, list/import codes, check availability
**QR Tracking** — list, create, delete links, analytics
**Merge Tags** — list available tags
