MCP Server

The mails0 MCP (Model Context Protocol) server gives AI assistants like Claude Desktop, Cursor, and Windsurf 11 email tools. It can start without credentials and create a safe temporary inbox on its first tool call.

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": ["-y", "mails-agent-mcp@2.2.0"]
    }
  }
}

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": ["-y", "mails-agent-mcp@2.2.0"]
    }
  }
}

Windsurf

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

{
  "mcpServers": {
    "mails-agent": {
      "command": "npx",
      "args": ["-y", "mails-agent-mcp@2.2.0"]
    }
  }
}

Self-hosted API

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

{
  "mcpServers": {
    "mails-agent": {
      "command": "npx",
      "args": ["mails-agent-mcp"],
      "env": {
        "MAILS_WORKER_TOKEN": "your_worker_token",
        "MAILS_MAILBOX": "[email protected]",
        "MAILS_API_URL": "https://your-worker.your-domain.workers.dev"
      }
    }
  }
}

Tools

The MCP server exposes 11 tools. It starts without credentials: call get_inbox, wait_for_code, or any other tool and the server automatically establishes a safe first mailbox.

create_temporary_mailbox

Create or reuse a random 72-hour receive-only mailbox without browser approval. The API key is stored locally with 0600 permissions and is never returned to the model.

send_email

Send an email from your mailbox.

Parameter	Type	Required	Description
to	string[]	Yes	Recipient email addresses
subject	string	Yes	Email subject
body	string	Yes	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

get_inbox

List recent emails.

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

search_inbox

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

get_attachment

Download an attachment by its ID.

Parameter	Type	Required	Description
id	string	Yes	Attachment 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)
since	string	No	Only return codes after this ISO timestamp

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
id	string	Yes	Thread ID

extract_data

Extract structured data from an email using AI.

Parameter	Type	Required	Description
email_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 mails0 API requests.

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

Mailbox data lives in the mails0 API. Local credentials are stored in ~/.mails/config.json; environment variables can override MAILS_API_URL, MAILS_API_KEY, MAILS_MAILBOX, and MAILS_WORKER_TOKEN.

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.
• With no credentials, call any tool. The server bootstraps a temporary mailbox automatically.

Authentication errors

• Verify your API key by running curl -s -H "Authorization: Bearer YOUR_KEY" https://api.mails0.com/v1/me
• Ensure you are using the correct key type. Provisional keys are receive-only; mailbox keys unlock normal mailbox capabilities; operator keys are reserved for provisioning and moderation.

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.