mcp-server-email

Multi-account email server for the Model Context Protocol. Gives LLMs full email access — read, send, search, organize — over IMAP/SMTP with connection pooling, rate limiting, and retry. Designed as the remote-email counterpart to apple-bridge (local Mail.app access).

Quick Start

1. Install

   bash

   Copy

   go install github.com/boutquin/mcp-server-email/cmd/mcp-server-email@latest
   

2. Create a config file (~/.config/mcp-email/accounts.json)

   For well-known providers (Gmail, Outlook, Yahoo, iCloud, Fastmail, Zoho), host and port are auto-detected from the email domain — just provide credentials:

   config.json

   Copy

   [
     {
       "id": "hello",
       "email": "hello@gmail.com",
       "username": "hello@gmail.com",
       "password": "app-password-here"
     }
   ]
   

   For custom mail servers, specify host and port explicitly:

   config.json

   Copy

   [
     {
       "id": "work",
       "email": "hello@example.com",
       "imap_host": "mail.example.com",
       "imap_port": 993,
       "smtp_host": "mail.example.com",
       "smtp_port": 465,
       "username": "hello@example.com",
       "password": "app-password-here"
     }
   ]
   

   bash

   Copy

   chmod 600 ~/.config/mcp-email/accounts.json
   

3. Add to Claude Code (~/.claude.json)

   config.json

   Copy

   {
     "mcpServers": {
       "email": {
         "command": "mcp-server-email",
         "env": {
           "EMAIL_CONFIG_FILE": "~/.config/mcp-email/accounts.json"
         }
       }
     }
   }
   

4. Restart Claude Code — the email_* tools are now available.

Installation

Go Install (recommended for Go developers)

go install github.com/boutquin/mcp-server-email/cmd/mcp-server-email@latest

Homebrew (macOS/Linux)

brew install boutquin/tap/mcp-server-email

Binary Download

Download pre-built binaries for your platform from GitHub Releases.

Available for: Linux (amd64, arm64), macOS (amd64, arm64), Windows (amd64, arm64).

Docker

docker run --rm \
  -e EMAIL_ACCOUNTS='[{"id":"main","email":"user@example.com","imap_host":"mail.example.com","imap_port":993,"smtp_host":"mail.example.com","smtp_port":465,"username":"user@example.com","password":"app-password"}]' \
  ghcr.io/boutquin/mcp-server-email:latest

MCP Bundle (Claude Desktop)

Download the .mcpb file from Releases and open in Claude Desktop.

Build from source

git clone https://github.com/boutquin/mcp-server-email.git
cd mcp-server-email
go build -o mcp-server-email ./cmd/mcp-server-email

Configuration

Accounts are loaded once at startup. Changes require a server restart.

Config file vs environment variable

If both are set, EMAIL_ACCOUNTS takes precedence.

Account JSON schema

[
  {
    "id": "hello",
    "email": "hello@example.com",
    "imap_host": "mail.example.com",
    "imap_port": 993,
    "smtp_host": "mail.example.com",
    "smtp_port": 465,
    "username": "hello@example.com",
    "password": "app-password-here"
  }
]

*Host and port are auto-detected for well-known providers (see below). Required for custom servers. **Not required when using OAuth2 authentication.

Provider auto-detection

When imap_host/smtp_host are omitted, the server detects settings from the email domain:

Explicit host/port in the config always takes precedence over auto-detection.

TLS modes

TLS mode is auto-detected from port:

Override with "use_starttls": true or "use_starttls": false in the account object. Omit for auto-detection (recommended).

OAuth2 authentication

For providers that support it (Gmail, Outlook), you can use OAuth2 instead of app passwords. This uses the device code flow (RFC 8628) — no browser redirect needed.

1. Create OAuth2 credentials in the provider's developer console (Google Cloud Console or Azure AD)

2. Configure the account with auth_method: "oauth2":

   config.json

   Copy

   [
     {
       "id": "gmail",
       "email": "user@gmail.com",
       "username": "user@gmail.com",
       "auth_method": "oauth2",
       "oauth_client_id": "your-client-id.apps.googleusercontent.com",
       "oauth_client_secret": "your-client-secret"
     }
   ]
   

3. On first connection, the server initiates the device code flow — printing a verification URL and code to stderr. Visit the URL and enter the code to authorize.

4. Tokens are persisted in ~/.config/mcp-email/tokens/ and automatically refreshed. Subsequent connections reuse the stored token without re-authorization.

Supported OAuth2 providers: Gmail (gmail.com, googlemail.com) and Outlook (outlook.com, hotmail.com, live.com).

Environment variables

*One of EMAIL_CONFIG_FILE or EMAIL_ACCOUNTS is required.

Config file permissions

The config file contains account passwords. Always restrict access:

chmod 600 ~/.config/mcp-email/accounts.json

Tools (22)

Account & folder tools

Message listing

Message operations