@gnidreve/classic-imap-smtp-mcp

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 and provides 32 tools for reading, writing, and managing email — nothing more, nothing less.

It can run either over classic stdio for local MCP clients or over HTTP with Streamable MCP plus a legacy SSE compatibility endpoint for container deployments.

Quick Start

npx @gnidreve/classic-imap-smtp-mcp

For container or remote MCP setups:

npx @gnidreve/classic-imap-smtp-mcp --transport=http --http-host=0.0.0.0 --http-port=3000

Set environment variables USERNAME and PASSWORD to connect your mailbox:

export USERNAME=you@example.com
export PASSWORD=your-app-password

For most providers (Gmail, Outlook, iCloud, etc.) that's all you need — IMAP/SMTP hosts are auto-detected. See docs/config.md for all available options.

Full installation instructions: docs/install.md

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

Wildcards match by prefix: imap_*, smtp_*, 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, 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 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.