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
-
Install
go install github.com/boutquin/mcp-server-email/cmd/mcp-server-email@latest -
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": "[email protected]", "username": "[email protected]", "password": "app-password-here" } ]For custom mail servers, specify host and port explicitly:
[ { "id": "work", "email": "[email protected]", "imap_host": "mail.example.com", "imap_port": 993, "smtp_host": "mail.example.com", "smtp_port": 465, "username": "[email protected]", "password": "app-password-here" } ]chmod 600 ~/.config/mcp-email/accounts.json -
Add to Claude Code (
~/.claude.json){ "mcpServers": { "email": { "command": "mcp-server-email", "env": { "EMAIL_CONFIG_FILE": "~/.config/mcp-email/accounts.json" } } } } -
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":"[email protected]","imap_host":"mail.example.com","imap_port":993,"smtp_host":"mail.example.com","smtp_port":465,"username":"[email protected]","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": "[email protected]",
"imap_host": "mail.example.com",
"imap_port": 993,
"smtp_host": "mail.example.com",
"smtp_port": 465,
"username": "[email protected]",
"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.
-
Create OAuth2 credentials in the provider's developer console (Google Cloud Console or Azure AD)
-
Configure the account with
auth_method: "oauth2":[ { "id": "gmail", "email": "[email protected]", "username": "[email protected]", "auth_method": "oauth2", "oauth_client_id": "your-client-id.apps.googleusercontent.com", "oauth_client_secret": "your-client-secret" } ] -
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.
-
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 parameter — an array of file references on the server host:
{
"attachments": [
{"path": "/tmp/report.pdf"},
{"path": "/tmp/data.csv", "filename": "Q1-data.csv", "content_type": "text/csv"}
]
}
Limits (defaults): 18 MB per file, 18 MB total (pre-base64 encoding; stays under 25 MB SMTP cap after encoding). Configurable via MAX_ATTACHMENT_SIZE_MB and MAX_TOTAL_ATTACHMENT_SIZE_MB environment variables.
Download limit: Attachment downloads (email_attachment_get) are capped at 25 MB by default, configurable via MAX_DOWNLOAD_SIZE_MB.
Validation failures (missing file, non-absolute path, size exceeded) return INVALID_ARGUMENT.
Message IDs
Message IDs are composite strings encoding account, mailbox, and UID:
{account}:{mailbox}:{uid}
Example: hello:INBOX:12345
All CRUD tools (email_get, email_move, email_copy, email_delete, email_mark_read, email_flag, email_draft_send) extract the account and folder from the ID — no separate params needed.
Error Codes
All errors are returned as MCP tool errors with a structured code prefix:
Resources
Comparison with apple-bridge
This server and apple-bridge share an Email model and parameter semantics (limit, includeBody, folder, query) so LLMs can work with both interchangeably. Key differences:
Development
Prerequisites
- Go 1.24+
- golangci-lint
- Docker (for integration tests only)
Build
go build ./...
Unit tests
make test
# or: go test -race -count=1 ./...
Unit tests use mock implementations of the imap.Operations and smtp.Operations interfaces — no live mail server needed.
Benchmarks
go test -bench=. -benchmem ./...
Fuzz testing
Fuzz targets ship with seed corpora in testdata/fuzz/ directories. Run a specific target:
go test -fuzz=FuzzParseMessageID ./internal/models/ -fuzztime=30s
Lint
make lint
# or: golangci-lint run ./...
Integration tests
Integration tests exercise the full IMAP/SMTP stack against a real mail server. They are isolated behind the integration build tag and never run during go test ./....
Mail server: Greenmail
Tests use Greenmail, a lightweight Java mail server packaged as a Docker image. Key details that affect how you run it:
Quick start (one command)
make test-integration
This starts a Greenmail container, runs all integration tests, then tears down the container — regardless of pass/fail.
Manual step-by-step
If you need to iterate on tests without restarting the container each time:
-
Start Greenmail
docker run -d --name greenmail \ -p 3465:3465 -p 3993:3993 \ -e "GREENMAIL_OPTS=-Dgreenmail.setup.test.all -Dgreenmail.users=test:[email protected] -Dgreenmail.hostname=0.0.0.0" \ greenmail/standalone:2.1.0Wait ~3 seconds for the JVM to start.
-
Run integration tests
TEST_IMAP_HOST=localhost TEST_IMAP_PORT=3993 \ TEST_SMTP_HOST=localhost TEST_SMTP_PORT=3465 \ [email protected] TEST_PASSWORD=password \ go test -tags=integration -race -v ./... -
Tear down when done
docker stop greenmail && docker rm greenmail
Test environment variables
*If the corresponding HOST variable is unset, that test file's tests are skipped with a message (not failed).
What the tests cover
IMAP (internal/imap/integration_test.go — 7 tests):
SMTP (internal/smtp/integration_test.go — 4 tests):
Troubleshooting
CI
Integration tests run automatically in GitHub Actions via the integration job in .github/workflows/ci.yml. The job uses a Greenmail service container — no manual Docker setup needed. See the workflow file for the exact configuration.
Coverage
To generate a combined unit + integration coverage report:
# With Greenmail running (see above):
TEST_IMAP_HOST=localhost TEST_IMAP_PORT=3993 \
TEST_SMTP_HOST=localhost TEST_SMTP_PORT=3465 \
[email protected] TEST_PASSWORD=password \
go test -tags=integration -race -coverprofile=coverage.out ./...
go tool cover -func=coverage.out | tail -1 # total percentage
go tool cover -html=coverage.out # open in browser
Architecture
mcp-server-email/
├── cmd/mcp-server-email/ # Entry point
└── internal/
├── auth/ # OAuth2 device code flow, XOAUTH2 SASL, token store
├── config/ # Multi-account configuration, provider auto-detection
├── imap/ # IMAP client (split by concern), connection pool, Operations interface
│ ├── client.go # Client struct, lifecycle, shared helpers
│ ├── client_messages.go # List, search, get, attachments
│ ├── client_folders.go # Folder ops, role cache
│ ├── client_drafts.go # Draft save/get/delete
│ ├── client_flags.go # Flags, move, copy, delete
│ └── pool.go # Connection pool with configurable close timeout
├── log/ # Structured logging (slog) initialization
├── models/ # Email model, message ID codec, error types
├── resources/ # email://status resource
├── retry/ # Token-bucket rate limiter
├── smtp/ # SMTP client, Operations interface
└── tools/ # 22 MCP tool handlers + registration
Tool handlers are decoupled from IMAP/SMTP clients via the imap.Operations and smtp.Operations interfaces, enabling comprehensive unit testing with mocks.
Dependencies
This project uses go-imap v2 (currently v2.0.0-beta.8).
The v2 API is not yet stable — breaking changes may occur before the v2.0.0 release.
We pin the exact version in go.mod and will upgrade promptly when stable is released.