Email MCP Server

An MCP (Model Context Protocol) server providing comprehensive email capabilities via IMAP and SMTP.

Enables AI assistants to read, search, send, manage, schedule, and analyze emails across multiple accounts. Exposes 47 tools, 7 prompts, and 6 resources over the MCP protocol with OAuth2 support (experimental), email scheduling, calendar extraction, analytics, provider-aware label management, real-time IMAP IDLE watcher with AI-powered triage, customizable presets and static rules, and a guided setup wizard.

Highlights

Table of Contents

• Highlights
• Security
• Background
• Install
• Usage
• API
• Maintainers
• Contributing
• License

Security

• All connections use TLS/STARTTLS encryption
• Passwords are never logged; audit trail records operations without credentials
• Token-bucket rate limiter prevents abuse (configurable per account)
• OAuth2 XOAUTH2 authentication for Gmail and Microsoft 365 (experimental)
• Attachment downloads capped at 5 MB with base64 encoding

Background

Most MCP email implementations provide only basic read/send. This server aims to be a full-featured email client for AI assistants, covering the entire lifecycle: reading, composing, managing, scheduling, and analyzing email — all from a single MCP server.

Key design decisions:

• XDG-compliant config — TOML at ~/.config/email-mcp/config.toml
• Multi-account — Operate across multiple IMAP/SMTP accounts simultaneously
• Layered services — Business logic is decoupled from MCP wiring for testability
• Provider auto-detection — Gmail, Outlook, Yahoo, iCloud, Fastmail, ProtonMail, Zoho, GMX

Install

Requires Node.js ≥ 22.

# Run directly (no install needed)
npx @codefuturist/email-mcp setup
# or
pnpm dlx @codefuturist/email-mcp setup

# Or install globally
npm install -g @codefuturist/email-mcp
# or
pnpm add -g @codefuturist/email-mcp

Docker

No Node.js required — just Docker.

# Latest stable release
docker pull ghcr.io/codefuturist/email-mcp:latest

# Pin to an exact version (immutable)
docker pull ghcr.io/codefuturist/email-mcp:0.2.3

# Auto-update patches within a minor version
docker pull ghcr.io/codefuturist/email-mcp:0.2

# Track a major version (won't cross breaking-change boundary)
docker pull ghcr.io/codefuturist/email-mcp:0

# Pin to an exact git commit (immutable, CI traceability)
docker pull ghcr.io/codefuturist/email-mcp:sha-abc1234

# Or build from source
docker build -t ghcr.io/codefuturist/email-mcp .

Tag convention: Tags follow bare semver (no v prefix), matching Docker ecosystem standards (e.g. node:24, nginx:1.25). The latest tag is only updated on stable releases, never pre-releases.