Email (IMAP/SMTP)

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

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

1. 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:

   [

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

For custom mail servers, specify host and port explicitly:

   [

{ "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" } ]

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

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

   {

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

1. 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)

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

   [

{ "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" } ]

1. 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.

1. 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

Attachments & threads

Send & drafts

All optional account params default to the configured default account.

Search

email_search searches both subject and body using IMAP SEARCH OR (SUBJECT "q") (BODY "q").

Optional filters narrow the candidate set server-side before body scanning:

The existing operation timeout (default 30s) prevents hung body searches on large mailboxes.

Attachments

email_send and email_draft_create accept an attachments p