classic-imap-smtp-mcp

A complete IMAP/SMTP MCP server for AI assistants. Everything a good email client does — and nothing beyond.

classic-imap-smtp-mcp connects any IMAP/SMTP mailbox to an AI assistant via the Model Context Protocol. It runs locally, supports multiple accounts, and provides 36 tools for reading, writing, and managing email — nothing more, nothing less.

Quick Start

npx @gnidreve/classic-imap-smtp-mcp

Set environment variables USERNAME and PASSWORD to connect your mailbox:

export [email protected]
export PASSWORD=your-app-password

[!TIP] For most providers (Gmail, Outlook, iCloud, etc.) that's all you need — IMAP/SMTP hosts are auto-detected. If you need custom hosts or want to avoid collisions, see docs/config.md.

Full installation instructions: docs/install.md

[!NOTE] With multiple accounts, each tool accepts an optional account parameter. Defaults to the account named in default_account.

[!NOTE] --safe and --readonly are combinable (--readonly is stricter and wins). --no-imap and --no-smtp together produce an empty server — this aborts at startup (almost certainly a config mistake).

[!TIP] Wildcards match by prefix: imap_*, smtp_*, account_*, meta_*, or finer imap_delete_*, imap_bulk_*, imap_get_*.

📚 Documentation Index

🚀 Getting Started

• Installation — Set up the server in 60 seconds with npx and your mailbox credentials
• Configuration — Environment variables, multi-account via TOML, CLI flags & tool filters

📖 Reference

• All 36 Tools — Complete tool reference with parameters
• Output Structures — What every tool returns (types, fields, examples)
• Provider Matrix — IMAP/SMTP host presets for 10+ mail providers

🛠️ Guides

• Client Setup — Config snippets for Cursor, Windsurf, VS Code, Claude Code
• Comparison — How this MCP compares to other mail servers

📄 Project

• Roadmap — Development phases from 0.3 to 1.0
• Contributing — Architecture, code style, how to contribute
• Security — Report vulnerabilities responsibly
• Changelog — Full release history

🤖 For LLM Agents

• llms.txt — Machine-readable guide for AI assistants to consume this server
• AGENTS.md — Technical architecture documentation for AI agents

Why this exists

Existing MCP mail servers are either incomplete, do too much (calendar, AI triage, scheduling), or lack features like multi-account, folder management, and fine-grained tool control. This project does one thing well: classic IMAP/SMTP — and makes every tool available through conditional registration so you control exactly what your AI assistant can do.

License

MIT — see LICENSE.