Mail MCP Server

Drive every StateSet Mail operation from Claude, Cursor, or any MCP client — tools, resources, and prompts over stdio or HTTP.

Mail MCP Server

StateSet Mail ships a Model Context Protocol server, so any MCP-capable client — Claude Desktop, Cursor, Claude Code, the Anthropic SDK — can drive every marketing and inbox operation as native tools.

The server advertises tools, resources, and prompts in its initialize response, so clients enable the Resources panel and Prompts catalog in their UI.

Transports

stdio — recommended for desktop clients

stateset-mail-mcp is a second binary that reads newline-delimited JSON-RPC from stdin and writes responses to stdout, logging to stderr. It reads the same environment variables as the main HTTP server — point both binaries at the same SQLite file and the MCP server sees everything the HTTP API has touched. All tools dispatch in-process, so there is no HTTP round-trip.

Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "stateset-mail": {
      "command": "/usr/local/bin/stateset-mail-mcp",
      "env": {
        "DATABASE_URL":           "sqlite:///Users/you/.stateset-mail/data/mail.db",
        "STATESET_MAIL_API_KEYS": "anything-nonempty-the-stdio-binary-doesnt-auth",
        "DEFAULT_FROM":           "Agent <[e-mail]>",
        "SMTP_HOST":              "smtp.example.com",
        "SMTP_USERNAME":          "[e-mail]",
        "SMTP_PASSWORD":          "...",
        "PUBLIC_BASE_URL":        "https://mail.example.com"
      }
    }
  }
}

Restart the client and the tools are live in the next chat.

HTTP — recommended for remote clients

POST /v1/mcp accepts a single JSON-RPC request and returns a single response, with the same bearer-token auth as the rest of /v1. Use this when the MCP client lives on a different machine from the deployment.

curl -sS -X POST -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://mail.example.com/v1/mcp | jq '.result.tools[].name'

The tool context carries tenant identity, so a multi-tenant deployment scopes calls correctly.

Tools

26 marketing tools cover profiles, lists, segments, templates, campaigns, flows, suppressions, events, webhooks, and the activity log — upsert_profile, add_to_list, preview_segment, create_campaign, send_campaign, get_campaign_stats, get_campaign_timeseries, suppress_email, track_event, and more.

A further set of conversation tools covers the agent inbox — see Conversations.

The same 14-function marketing surface is also available as plain OpenAI- and Anthropic-format tool schemas at GET /v1/tools, if you’d rather wire it into an agent directly than go through MCP.

Resources

resources/list enumerates recently-touched entities; resources/read returns the full JSON body for one. Resources let a model read state without burning a tool call, and clients render them in a panel so you can attach an entity to a chat with one click.

URI	What it returns
profile://EMAIL	The full profile — consent, properties, timezone
list://UUID	List metadata plus up to 200 member previews
list://name/NAME	The same, looked up by list name
segment://UUID	Definition, evaluated count, and a sample
template://UUID	Subject, HTML, text, and MJML source if any
campaign://UUID	Campaign plus live stats

Prompts

prompts/list advertises server-provided playbooks; prompts/get renders the body with the caller’s arguments substituted in. Each names the tools to call and the order to call them, so picking a prompt is a one-shot way to trigger a multi-step workflow.

Name	Arguments
draft_welcome_campaign	list_name (required), brand_voice
analyze_campaign	campaign_id (required)
propose_engagement_segment	kind (required), window_days
audit_suppressions	—
design_reengagement_flow	—
triage_inbox	—

Related

• Overview
• Conversations
• MCP Integration Guide
• All MCP servers