Setting Up Claude Code with AgentMail MCP

This guide walks through connecting Claude Code to AgentMail’s MCP server so your AI agent can read, send, and manage email — all from the command line.

What You Get

Once configured, Claude Code gains access to email tools: create inboxes, send messages, read incoming mail, reply to threads, forward messages, and manage attachments. You interact with email through natural language. “Check my inbox for anything from Acme Corp” or “Reply to that thread and attach the proposal” — Claude handles the MCP tool calls behind the scenes.

Prerequisites

Step 1: Get Your AgentMail API Key

  1. Sign up at agentmail.to
  2. Open the AgentMail Console
  3. Generate an API key
  4. Copy it — you’ll need it in the next step

Step 2: Configure Claude Code

Claude Code reads MCP server configuration from ~/.claude/claude_desktop_config.json (or your project’s .mcp.json). Add the AgentMail server:

Option A: Global Configuration

Edit ~/.claude/claude_desktop_config.json:

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

Option B: Project-Level Configuration

Create .mcp.json in your project root:

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

Project-level config keeps the API key scoped to one project and out of your global settings.

Option C: Selective Tools Only

If you don’t want Claude to have access to every email operation, restrict the tools:

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

This limits Claude to listing inboxes, reading messages, and sending — no deleting, no forwarding, no inbox creation. Useful when you want guardrails.

Step 3: Restart Claude Code

After saving the config, restart Claude Code so it picks up the new MCP server:

claude

On startup, Claude Code connects to the AgentMail MCP server via npx. The first run downloads the package — subsequent runs use the cached version.

Step 4: Verify the Connection

Ask Claude to list available tools:

> What AgentMail tools do you have access to?

You should see tools like list_inboxes, create_inbox, get_message, send_message, reply_to_message, and others depending on your --tools filter.

Reading Mail

List Your Inboxes

> List all my AgentMail inboxes

Claude calls list_inboxes and returns a summary of each inbox with its ID, address, and display name.

Read Messages

> Show me the latest messages in my inbox
> Read the message from [email protected] about the Q2 report

Claude calls list_messages on the inbox, then get_message for specific messages. It presents the content in a readable format — sender, subject, date, and body.

Browse Threads

> Show me the thread with Acme Corp about the partnership

Claude uses list_threads and get_thread to reconstruct the conversation in order.

Sending Mail

Send a New Message

> Send an email from my inbox to [email protected]
> Subject: Project kickoff
> Body: Hi Bob, confirming our meeting tomorrow at 2pm. I'll send the agenda beforehand.

Claude calls send_message with the inbox ID, recipient, subject, and body. It confirms the message was sent and shows the message ID.

Reply to a Message

> Reply to the last message from Sarah saying "Thanks, I'll review the report by Friday"

Claude calls reply_to_message with the original message ID and your reply content. The reply stays in the same thread.

Forward a Message

> Forward that Acme partnership email to the team at [email protected]

Claude calls forward_message with the message ID and the new recipient.

Managing Inboxes

Create a New Inbox

> Create a new inbox called "support" for handling customer emails

AgentMail creates an inbox with a generated email address on your verified domain (or a default @inbox.agentmail.to address).

Delete an Inbox

> Delete the old test inbox

Claude calls delete_inbox. This is permanent — all messages in the inbox are lost.

Security Considerations

API key exposure. The API key sits in a JSON config file on your machine. Keep it out of version control:

# .gitignore
.mcp.json

Or use the global config (~/.claude/claude_desktop_config.json) so the key never enters a project directory.

Tool restriction. Use --tools to limit what Claude can do. If you only need to read mail, don’t give it send_message or delete_inbox. Principle of least privilege applies to AI agents too.

No approval gate. By default, Claude Code prompts before executing MCP tool calls. Keep this enabled — it means you review every email before it’s sent. If you’ve configured auto-approve for AgentMail tools, every natural language request translates directly to an API call with no human in the loop.

Troubleshooting

“MCP server failed to start” — Check that Node.js 18+ is installed (node --version). The npx command needs a working Node environment.

“AGENTMAIL_API_KEY not set” — Verify the env block in your config has the correct key name and value. No quotes around the key name, quotes around the value.

“Tool not found” — If you used --tools to filter, make sure the tool name matches exactly. Run without --tools first to see all available tools, then restrict.

Slow first run — The first npx -y agentmail-mcp downloads the package from npm. Subsequent runs use the local cache and start in seconds.

Permission denied on send — Verify your AgentMail API key has send permissions and that the inbox you’re sending from belongs to your account.

Putting It All Together

A typical workflow looks like this:

> Check my inbox for any new messages today

Found 3 new messages:
1. From: [email protected] — "Q2 Report Draft" (10:23 AM)
2. From: [email protected] — "Invoice #4821" (9:15 AM)
3. From: [email protected] — "Weekend plans?" (8:42 AM)

> Reply to Sarah: "Looks good, just two comments on page 4.
> The revenue projection needs updating and the chart legend
> is missing. Otherwise ready to ship."

Sent reply to [email protected] in thread "Q2 Report Draft".
Message ID: msg_abc123

> Forward the invoice to [email protected] with a note:
> "Please process — net 30 terms"

Forwarded to [email protected].

Three emails handled in under a minute without leaving the terminal. That’s the point — email becomes another tool in your development workflow, managed by the same AI agent that writes your code, runs your tests, and manages your infrastructure.