AgentMail MCP Server

Connect AgentMail to any MCP-compatible AI client. Three setup options available.

Prerequisites

Get your API key from console.agentmail.to.

Option 1: Remote MCP (Simplest)

No installation required. Connect directly to the hosted MCP server.

URL: https://mcp.agentmail.to

Authentication: OAuth 2.0 via Smithery. The remote server does NOT accept an API key in env — it returns 401 Bearer error="invalid_token" and redirects your MCP client through the OAuth authorization server at https://auth.smithery.ai/agentmail. The MCP client handles the browser-based consent flow automatically on first connect.

Add to your MCP client configuration:

{
  "mcpServers": {
    "AgentMail": {
      "url": "https://mcp.agentmail.to"
    }
  }
}

On first use, your MCP client opens a browser window to complete the Smithery OAuth flow; after approval, tokens are cached by the client. If you need API-key auth (no OAuth flow), use Option 2 or Option 3 below instead.

Option 2: Local npm Package

Run the MCP server locally via npx.

{
  "mcpServers": {
    "AgentMail": {
      "command": "npx",
      "args": ["-y", "agentmail-mcp"],
      "env": {
        "AGENTMAIL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Tool Selection

Load only specific tools with the --tools argument:

{
  "mcpServers": {
    "AgentMail": {
      "command": "npx",
      "args": [
        "-y",
        "agentmail-mcp",
        "--tools",
        "send_message,reply_to_message,list_inboxes"
      ],
      "env": {
        "AGENTMAIL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Option 3: Local Python Package

Install and run the Python MCP server.

pip install agentmail-mcp

Claude Desktop

Config location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

The server accepts the API key in two ways: via AGENTMAIL_API_KEY env var, or via the --api-key CLI flag. Use whichever works in your MCP client's launcher environment.

{
  "mcpServers": {
    "AgentMail": {
      "command": "/path/to/your/.venv/bin/agentmail-mcp",
      "env": {
        "AGENTMAIL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

If env vars don't propagate through your MCP launcher, pass the key as an argument instead:

{
  "mcpServers": {
    "AgentMail": {
      "command": "/path/to/your/.venv/bin/agentmail-mcp",
      "args": ["--api-key", "YOUR_API_KEY"]
    }
  }
}

Find your path:

# Activate your virtual environment, then:
which agentmail-mcp

Run Standalone

# Option A: env var
export AGENTMAIL_API_KEY=your-api-key
agentmail-mcp

# Option B: CLI flag (useful if env vars aren't available)
agentmail-mcp --api-key="your-api-key"

Available Tools

The Node MCP server (npx agentmail-mcp, Option 1 and Option 2) exposes 17 tools:

Tool	Description
`create_inbox`	Create a new email inbox
`list_inboxes`	List all inboxes
`get_inbox`	Get inbox details by ID
`delete_inbox`	Delete an inbox
`send_message`	Send an email from an inbox
`reply_to_message`	Reply to an existing message
`forward_message`	Forward an existing message
`list_threads`	List email threads in an inbox
`get_thread`	Get thread details and messages
`get_attachment`	Download an attachment
`update_message`	Update message labels
`create_draft`	Create a draft message
`list_drafts`	List drafts in an inbox
`get_draft`	Get a draft by ID
`update_draft`	Update a draft
`send_draft`	Send a previously-created draft
`delete_draft`	Delete a draft without sending

The legacy Python MCP server (pip install agentmail-mcp, Option 3) is a separate codebase with a smaller tool set — it omits the six *_draft tools above. For new projects, prefer the Node server (Option 1 or Option 2) for full parity with the toolkit.

Client Configuration

Cursor, VS Code, Windsurf

Add the same MCP server entry in your client config file:

Cursor: .cursor/mcp.json
VS Code: .vscode/mcp.json
Windsurf: MCP config file

{
  "mcpServers": {
    "AgentMail": {
      "command": "npx",
      "args": ["-y", "agentmail-mcp"],
      "env": {
        "AGENTMAIL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Compatible Clients

The AgentMail MCP server works with any MCP-compatible client:

Claude Desktop
Cursor
VS Code
Windsurf
Cline
Goose
Raycast
ChatGPT
Amazon Q
Codex
Gemini CLI
LibreChat
Roo Code
And more...

Example Usage

Once configured, you can ask your AI assistant:

"Create a new inbox for support emails"
"Send an email to john@example.com with subject 'Hello'"
"Check my inbox for new messages"
"Reply to the latest email thanking them"
"List all my email threads"
"Download the attachment from the last message"

Troubleshooting

"Command not found"

Ensure npm/npx is in your PATH, or use the full path:

"command": "/usr/local/bin/npx"

"Invalid API key"

Verify your API key is correct and has the necessary permissions.

Python package not found

Use the full path to the agentmail-mcp executable in your virtual environment:

# Find the path
source /path/to/venv/bin/activate
which agentmail-mcp

agentmail-mcp