AI & Integrations

MCP Server

Cleanmails includes a built-in Model Context Protocol (MCP) server that lets you control your outreach platform directly from AI coding assistants like Claude Desktop, Cursor, or any MCP-compatible client.

What is MCP?

MCP (Model Context Protocol) is an open standard that allows AI assistants to interact with external tools. The Cleanmails MCP server exposes your campaigns, mailboxes, leads, and inbox as tools that an AI can read and control.

Available Tools

Tool	Description
`get_stats`	Get overall outreach statistics (sent, opens, replies, bounces)
`list_campaigns`	List all campaigns with current status and stats
`start_campaign`	Start a draft or paused campaign
`pause_campaign`	Pause a running campaign
`list_leads`	List leads with filtering options
`get_inbox`	Get recent email threads/replies
`send_reply`	Send a reply to a thread
`get_mailboxes`	List all mailbox accounts with health status

Architecture

The MCP server is built into the Cleanmails API as an HTTP endpoint at /api/v1/mcp. It uses JSON-RPC 2.0 protocol and requires authentication (JWT token or API key).

A standalone MCP binary (cleanmails-mcp) is included in your installation that bridges between the stdio transport (used by Claude/Cursor) and the HTTP endpoint.

Setup for Claude Desktop

Download the MCP binary

The MCP server binary is included in your Cleanmails installation at /opt/cleanmails/cleanmails-mcp. Copy it to your local machine.

Get your API key

Go to your Cleanmails dashboard → Settings → API & MCP tab, and generate an API key. It will have the format cm_live_xxx.

Configure Claude Desktop

Edit your Claude Desktop MCP config file:

claude_desktop_config.json

{
  "mcpServers": {
    "cleanmails": {
      "command": "/path/to/cleanmails-mcp",
      "args": [
        "--api-url", "https://your-cleanmails-domain.com",
        "--api-key", "cm_live_YOUR_API_KEY"
      ]
    }
  }
}

Restart Claude Desktop

After saving the config, restart Claude Desktop. You should see "cleanmails" appear in the available tools list.

Setup for Cursor

The same binary works with Cursor. Add it to your .cursor/mcp.json:

.cursor/mcp.json

{
  "mcpServers": {
    "cleanmails": {
      "command": "/path/to/cleanmails-mcp",
      "args": ["--api-url", "https://your-domain.com", "--api-key", "cm_live_YOUR_KEY"]
    }
  }
}

Environment Variables

Instead of CLI flags, you can use environment variables:

Variable	Description
`CLEANMAILS_API_URL`	Your Cleanmails server URL (e.g., https://app.yourdomain.com)
`CLEANMAILS_API_KEY`	Your API key (cm_live_xxx format)

Direct HTTP Usage

You can also call the MCP endpoint directly via HTTP for custom integrations:

bash

curl -X POST https://YOUR_SERVER/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=YOUR_JWT_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_stats",
      "arguments": {}
    }
  }'

Example Usage

Once connected, you can ask your AI assistant things like:

"Show me my campaign stats"
"Pause the Q2 Outreach campaign"
"List my mailboxes and their health status"
"Check my inbox for new replies"
"Send a reply to the latest thread"
"Start the Enterprise campaign"

Protocol Version

The Cleanmails MCP server implements JSON-RPC 2.0. The standalone binary uses stdio transport (stdin/stdout) for compatibility with Claude Desktop and Cursor.

Troubleshooting

Issue	Solution
Tools not appearing	Check that the binary path is correct and executable (`chmod +x`)
API errors (401)	Your API key may be invalid — generate a new one from the dashboard
Connection refused	Ensure your Cleanmails server is running and accessible from your machine
Wrong workspace	API keys are scoped to a workspace — ensure you're using the right key