MCP Server

The mails-agent MCP (Model Context Protocol) server gives AI assistants like Claude Desktop, Cursor, and Windsurf the ability to send, receive, and manage email. It exposes 10 tools that the AI can call directly.

Installation

Run the MCP server directly with npx (no global install needed):

npx mails-agent-mcp

Or install globally:

npm install -g mails-agent-mcp
mails-agent-mcp

Configuration

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "mails-agent": {
      "command": "npx",
      "args": ["mails-agent-mcp"],
      "env": {
        "MAILS_API_KEY": "mk_your_api_key"
      }
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Cursor

Add the MCP server in Cursor settings under Features → MCP Servers:

{
  "mcpServers": {
    "mails-agent": {
      "command": "npx",
      "args": ["mails-agent-mcp"],
      "env": {
        "MAILS_API_KEY": "mk_your_api_key"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration (~/.windsurf/mcp_config.json):

{
  "mcpServers": {
    "mails-agent": {
      "command": "npx",
      "args": ["mails-agent-mcp"],
      "env": {
        "MAILS_API_KEY": "mk_your_api_key"
      }
    }
  }
}

Self-hosted API

If you self-host mails-agent, add the API URL to the environment:

{
  "mcpServers": {
    "mails-agent": {
      "command": "npx",
      "args": ["mails-agent-mcp"],
      "env": {
        "MAILS_API_KEY": "mk_your_api_key",
        "MAILS_API_URL": "https://your-worker.your-domain.workers.dev"
      }
    }
  }
}

Tools

The MCP server exposes 10 tools. After configuration, the AI assistant can call any of these directly.

send_email

Send an email from your mailbox.

Parameter	Type	Required	Description
to	string[]	Yes	Recipient email addresses
subject	string	Yes	Email subject
text	string	No*	Plain text body
html	string	No*	HTML body
cc	string[]	No	CC recipients
bcc	string[]	No	BCC recipients
in_reply_to	string	No	Message ID for threading

* At least one of text or html is required.

get_inbox

List recent emails.

Parameter	Type	Required	Description
limit	number	No	Max results (default 20)
offset	number	No	Pagination offset

search_emails

Semantic search across emails.

Parameter	Type	Required	Description
query	string	Yes	Natural language search query
limit	number	No	Max results (default 10)

get_email

Get a single email by ID.

Parameter	Type	Required	Description
id	string	Yes	Email message ID

delete_email

Delete a single email.

Parameter	Type	Required	Description
id	string	Yes	Email message ID

wait_for_code

Wait for a verification code to arrive. Polls the inbox until a code is extracted or the timeout is reached.

Parameter	Type	Required	Description
timeout	number	No	Max seconds to wait (default 60)
sender	string	No	Only match codes from this sender

get_threads

List email threads.

Parameter	Type	Required	Description
limit	number	No	Max results (default 20)
offset	number	No	Pagination offset

get_thread

Get all messages in a thread.

Parameter	Type	Required	Description
thread_id	string	Yes	Thread ID

get_me

Get information about the authenticated key and mailbox. No parameters.

extract_data

Extract structured data from an email using AI.

Parameter	Type	Required	Description
message_id	string	Yes	Email message ID
type	string	Yes	Extraction type: order, shipping, calendar, receipt, or code

Usage Examples

Once configured, you can ask your AI assistant to perform email tasks in natural language:

• "Check my inbox for new emails"
• "Send an email to [email protected] with the subject 'Meeting Notes' and the summary from our conversation"
• "Search my emails for anything from GitHub about pull requests"
• "Wait for a verification code and tell me what it is"
• "Extract the order details from the latest Amazon confirmation email"
• "Show me all threads about the marketing campaign"

How It Works

The MCP server runs as a local process and communicates with the AI client via the Model Context Protocol (stdio transport). It translates tool calls from the AI into mails-agent API requests.

AI Assistant  --MCP-->  mails-agent-mcp  --HTTP-->  mails-agent API
   (Claude)            (local process)            (Cloudflare Worker)

The MCP server itself is stateless. All state lives in the mails-agent API. The server needs only the API key to function.

Troubleshooting

Tools not appearing

• Restart the AI client after editing the config file.
• Ensure npx mails-agent-mcp runs without errors when executed manually in the terminal.
• Check that MAILS_API_KEY is set in the env block.

Authentication errors

• Verify your API key by running curl -s -H "Authorization: Bearer YOUR_KEY" https://mails-worker.genedai.workers.dev/v1/me
• Ensure you are using the correct key type. Mailbox-scoped keys work for most tools. Domain management requires a full-access key.

Timeout on wait_for_code

• The default timeout is 60 seconds. If the verification email takes longer, increase the timeout.
• Use the sender parameter to avoid matching codes from unrelated emails.