Email MCP server for AI agents

What it does

Connect mail-mcp to Claude Code, Claude Desktop, Cursor or any MCP client and the agent can work with your inbox: find a thread, summarize it, draft and send a reply with the right threading headers, file messages into folders, or clean up hundreds of messages in one call. It runs on your machine and talks directly to your mail provider, so credentials and messages never pass through a third party.

Supported email providers

All accounts can be configured at once; every tool takes an account_id.

Install

Linux and macOS

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/tecnologicachile/mail-mcp/releases/latest/download/mail-mcp-installer.sh | sh

Windows (PowerShell)

powershell -ExecutionPolicy Bypass -c "irm https://github.com/tecnologicachile/mail-mcp/releases/latest/download/mail-mcp-installer.ps1 | iex"

Docker

docker run --rm -i --env-file .env ghcr.io/tecnologicachile/mail-mcp

From source

git clone https://github.com/tecnologicachile/mail-mcp.git
cd mail-mcp && cargo build --release

Add it to your MCP client

Example for Gmail with an app password. The same block works in Claude Code, Claude Desktop, Cursor and other MCP clients.

{
  "mcpServers": {
    "mail": {
      "command": "mail-mcp",
      "env": {
        "MAIL_IMAP_DEFAULT_HOST": "imap.gmail.com",
        "MAIL_IMAP_DEFAULT_USER": "you@gmail.com",
        "MAIL_IMAP_DEFAULT_PASS": "your-app-password",
        "MAIL_SMTP_DEFAULT_HOST": "smtp.gmail.com",
        "MAIL_SMTP_DEFAULT_PORT": "587",
        "MAIL_SMTP_DEFAULT_USER": "you@gmail.com",
        "MAIL_SMTP_DEFAULT_PASS": "your-app-password",
        "MAIL_SMTP_DEFAULT_SECURE": "starttls",
        "MAIL_IMAP_WRITE_ENABLED": "true",
        "MAIL_SMTP_WRITE_ENABLED": "true"
      }
    }
  }
}

For Microsoft 365 and Outlook.com, see the account setup guide for the EWS and Graph device-code flow.

31 MCP tools

Read

• list_all_accounts accounts and their capabilities
• imap_list_accounts
• imap_verify_account test connection and auth
• imap_list_mailboxes list folders
• imap_mailbox_status message counts
• imap_search_messages search with pagination
• imap_get_message parsed message
• imap_get_message_raw RFC 822 source
• imap_get_attachment save an attachment to disk

Write and organize

• imap_update_message_flags
• imap_copy_message also across accounts
• imap_move_message
• imap_delete_message
• imap_create_mailbox
• imap_delete_mailbox
• imap_rename_mailbox
• imap_append_message
• imap_bulk_move up to 500 messages
• imap_bulk_delete up to 500 messages
• imap_bulk_update_flags up to 500 messages
• imap_search_and_move
• imap_search_and_delete

Send

• smtp_send_message
• smtp_reply_message threaded replies
• smtp_forward_message
• smtp_verify_account
• graph_send_message Microsoft Graph

Exchange Web Services

• ews_search_messages
• ews_get_message
• ews_send_message

Setup

• get_setup_guide step-by-step account configuration

Full input and output contract: docs/tool-contract.md.

Security by default

Frequently asked questions

How do I give Claude access to my email?

Install mail-mcp, add it as an MCP server in Claude Code, Claude Desktop or any MCP client, and configure your account with environment variables. The agent then gets tools to search, read, send, reply, forward and organize email.

Does mail-mcp work with Outlook.com, Hotmail and Microsoft 365?

Yes. Microsoft blocks SMTP on personal accounts, so mail-mcp sends through Microsoft Graph API or Exchange Web Services (EWS) instead. EWS is the simplest option: one OAuth2 token covers reading and sending, and it works on tenants that block Graph and IMAP.

Can the AI agent send email, or only read it?

Both. Reading is enabled by default. Moving, deleting and sending stay disabled until you set MAIL_IMAP_WRITE_ENABLED=true and MAIL_SMTP_WRITE_ENABLED=true, and deletes also require confirm: true.

Does mail-mcp support Gmail, iCloud, Zoho and Fastmail?

Yes. Any provider that offers IMAP and SMTP works, including Gmail (with an app password or OAuth2), Apple iCloud, Zoho, Fastmail and self-hosted mail servers.

Does it support OAuth2?

Yes. mail-mcp implements XOAUTH2 natively for IMAP and SMTP, plus OAuth2 for Microsoft Graph and EWS, with cached tokens that refresh automatically.

Is there a Docker image?

Yes: ghcr.io/tecnologicachile/mail-mcp. Prebuilt binaries for Linux, macOS and Windows are also available on GitHub Releases.

Is mail-mcp free?

Yes. mail-mcp is open source under the MIT license and runs on your own machine, so your credentials and mail never go through a third-party service.