IMAP Wizard
Enables AI assistants to read, search, send, reply to, forward, and organize Gmail messages via IMAP/SMTP, with automatic provider detection and multi-account support.
Enables AI assistants to read, search, send, reply to, forward, and organize GMX email over IMAP/SMTP, with automatic provider detection.
Enables AI assistants to read, search, send, reply to, forward, and organize iCloud email over IMAP/SMTP, with automatic provider detection.
Supports Proton Mail through Proton Mail Bridge, allowing AI assistants to read, search, send, reply to, forward, and organize mail over IMAP/SMTP.
Enables AI assistants to read, search, send, reply to, forward, and organize Zoho email over IMAP/SMTP, with automatic provider detection.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
IMAP Wizard
Give your AI assistant your email, on your terms. A local MCP server that lets Claude, Codex, Cursor, VS Code, OpenCode or any MCP client read, search, send and organize mail over plain IMAP and SMTP. No cloud service in the middle.
Quick start · Why this one · Safety · Tools · Config · Troubleshooting · Upstream
A fork, credited. IMAP Wizard is a fork of codefuturist/email-mcp by @codefuturist, under the same LGPL-3.0-or-later license. It keeps upstream's design and history, fixes bugs upstream still has, and adds safety features. The package and command are called
imap-wizard. See Relationship to upstream.
Quick start
You need Node.js 24+.
npx -y imap-wizard account add # wizard; auto-detects common providers
npx -y imap-wizard test # checks IMAP and SMTP for every account
npx -y imap-wizard install # registers the server with detected MCP clientsOr add it to a client by hand. Claude Code:
claude mcp add email -- npx -y imap-wizard stdioClaude Desktop, Cursor and most other clients take the same JSON shape:
{
"mcpServers": {
"email": {
"command": "npx",
"args": ["-y", "imap-wizard", "stdio"]
}
}
}Prefer a global command? npm i -g imap-wizard, then run imap-wizard account add
and so on. To build from source instead:
git clone https://github.com/Fe2-O3/imap-wizard.git
cd imap-wizard
pnpm install && pnpm build
node dist/main.js account addand point the client at node /absolute/path/to/imap-wizard/dist/main.js stdio.
Ask your assistant "What's unread in my inbox?" to check it works. Setup for other clients is under More clients.
An existing~/.config/email-mcp config keeps working unchanged.
Related MCP server: Classic Mail
What you can ask for
Say this | What runs |
"What's unread and older than a week?" |
|
"Find the Acme invoice from this month and save the PDF to my Downloads folder" |
|
"Reply to that thread: Thursday works, cc billing" |
|
"Is this sender legit?" |
|
"Triage my inbox and skip the newsletters" |
|
"Move last month's receipts into Receipts" |
|
Why this one
Bugs fixed that upstream still has. As of upstream v0.6.0: duplicate sends on retry,
read_onlynot stopping background mail, stdio processes that never exit, "Re: RE:" subjects stacking, and Sent copies rejected by strict servers. Several others we fixed first have since been fixed upstream too. Full list with upstream status.Reading never changes your mailbox.
get_emailfetches with IMAPBODY.PEEK, so mail you read stays unread unless you ask (markRead: true).A real read-only mode. With
read_only = true, write tools are not registered at all, so the assistant cannot even see them.Works on big mailboxes. UID fetches are sent in chunks of 400, so a mailbox with tens of thousands of messages does not overflow the server's command limit.
No plaintext passwords required. Use the macOS Keychain, Linux
secret-tool, apassword_command(1Password, Bitwarden,pass), or OAuth2.Local and inspectable. A local process talks straight to your mail provider. No proxy, no telemetry, no account to create.
Safety and privacy
Control | Default | What it does |
Non-destructive reads | always |
|
| off | Hides every write tool and stops background services. |
Send rate limit | 10 per minute per account |
|
Audit log | on | Writes are logged, with sensitive fields redacted, to |
Duplicate-send guard | on | A retried send is recognized and refused unless you pass |
HTTP transport token | required |
|
Verification-code tool | off |
|
Body cache ( | off | Message bodies are only stored on disk if you turn it on. Details |
What is stored on disk by default: your config.toml (written owner-only), the
audit log, and a local SQLite mirror of message headers and flags for INBOX
over the last 90 days (settings.cache.enabled, on by default; set it to
false to turn the mirror off). Message bodies are not stored unless you enable
read_through.
To report a vulnerability, follow SECURITY.md. Please do not post exploits in public.
What it can do
50 tools (25 read, 25 write) plus 1 opt-in tool, 7 prompts and 6 resources. In read-only mode only the 25 read tools are registered.
Group | Tools |
Read mail |
|
Calendar (read) |
|
Watcher (read) |
|
Send (write) |
|
Schedule (write) |
|
Organize (write) |
|
Labels (write) |
|
Calendar and alerts (write) |
|
Opt-in |
|
Prompts: triage_inbox summarize_thread compose_reply
draft_from_context extract_action_items summarize_meetings cleanup_inbox
Resources: email://accounts email://{account}/mailboxes
email://{account}/unread email://{account}/stats email://templates
email://scheduled
Also included: multi-account support, Streamable HTTP transport, an IMAP IDLE
watcher with optional AI triage through MCP sampling (off by default), provider
auto-detection for Gmail, Outlook, Yahoo, iCloud, Fastmail, Proton Mail Bridge,
Zoho and GMX, and a terminal CLI (list, read, search, send and more).
Configuration
Config lives at ~/.config/email-mcp/config.toml (node dist/main.js config path
prints it). The account add wizard writes it for you. A typical file:
[settings]
read_only = false # true hides every write tool
rate_limit = 10 # max sends per minute per account
[[accounts]]
name = "personal"
email = "you@example.com"
full_name = "Your Name"
password = "use_keychain:personal" # stored in the OS keychain
[accounts.imap]
host = "imap.example.com"
port = 993
tls = true
[accounts.smtp]
host = "smtp.example.com"
port = 465
tls = trueCheck any edit with node dist/main.js config validate. It names the bad line,
suggests fixes for typo'd keys, and exits 1 on errors, so it also works in CI.
OS keychain:
password = "use_keychain:<name>". macOS uses Keychain, Linux usessecret-tool(libsecret).node dist/main.js keychain migratemoves existing plaintext passwords over.Password command:
password_command = "op read 'op://Private/mail/password'"(orbw get password ...,pass show ...). It runs once at startup, must print the password to stdout, and is killed after 10 seconds. It wins overpasswordif both are set.OAuth2: an
[accounts.oauth2]block instead of a password.Plaintext: allowed, written readable only by you.
config showmasks it.
Set MCP_EMAIL_ADDRESS, MCP_EMAIL_PASSWORD (or MCP_EMAIL_PASSWORD_COMMAND),
MCP_EMAIL_IMAP_HOST and MCP_EMAIL_SMTP_HOST. Settings have matching
variables, for example MCP_EMAIL_READ_ONLY=true, MCP_EMAIL_RATE_LIMIT,
MCP_EMAIL_IDLE_EXIT and MCP_EMAIL_SEND_MAX_ATTACHMENT_MB.
Setting | Default | Meaning |
|
| Seconds without a request before the stdio server exits. A backstop for clients that never close the pipe |
|
| Cap on attachments per message. Known providers may lower it; an account-level |
|
| Local header-and-flags mirror ( |
|
| IMAP IDLE watcher for new mail, with optional hooks and alerts |
|
| Registers |
Local body cache (opt-in)
Merged on the development branch, off by default, and not yet in a tagged release.
With read_through = true, get_email keeps a decoded copy of each message it
reads. A message's body never changes for a given mailbox generation and UID, so
a repeat read only asks the server for current flags, then answers from disk.
Flags are always live, and a message that was moved or deleted is still reported
as not found.
[settings.cache]
read_through = true # default false
offline_reads = true # serve cached bodies, with a warning, when the server is unreachable
body_max_mb = 200 # LRU budget for cached bodies
body_messages = 500 # background backfill: newest N messages per synced mailbox (0 = off)Measured with scripts/bench-get-email.ts on one
real account (30 INBOX messages, 60 samples): a cached read took 174 ms at
p50 versus 714 ms for a live read. Your numbers will depend on your
provider and network.
Bodies over 256 KB are never cached. The cache file is
~/.cache/email-mcp/cache.db (mode 0600). Delete it while the server is
stopped to clear it. See SECURITY.md before turning this on, and
pair it with full-disk encryption.
More clients
{
"mcpServers": {
"email": {
"command": "node",
"args": ["/absolute/path/to/imap-wizard/dist/main.js", "stdio"]
}
}
}{
"mcp": {
"servers": {
"email": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/imap-wizard/dist/main.js", "stdio"]
}
}
}
}[mcp_servers.email]
command = "node"
args = ["/absolute/path/to/imap-wizard/dist/main.js", "stdio"]Raise the timeout: a full-text search over a very large mailbox can take longer than the 60-second default.
{
"mcp": {
"email": {
"type": "local",
"command": ["node", "/absolute/path/to/imap-wizard/dist/main.js", "stdio"],
"enabled": true,
"timeout": 180000
}
}
}node dist/main.js http --port 8080On first run it generates a bearer token, prints it once, and saves it to
~/.config/email-mcp/http-token. Send it with every request:
{
"mcpServers": {
"email": {
"type": "streamable-http",
"url": "http://127.0.0.1:8080/mcp",
"headers": { "Authorization": "Bearer <your token>" }
}
}
}It refuses to bind a non-loopback address without a token.
Troubleshooting
Symptom | Likely cause | Fix |
| Your client stops waiting after 60 s; a full-text search on a huge mailbox can take longer | Raise the client timeout ( |
Setup says the config file is invalid | A TOML syntax or key error |
|
Login fails | Wrong password, or the provider needs an app password | The error now shows the server's own reason; run |
Search returns nothing on a server you know has mail | Some servers return malformed SEARCH replies | This build fails loudly instead of reporting zero results; check the error |
A server process keeps running after you quit | Your client never closes the pipe | Set |
| The old server process is still running | Restart your client (in Claude Code: |
Relationship to upstream
This project began as a fork of
codefuturist/email-mcp at commit
7fe8916 (2026-08-21) and started its own version line at
v0.1.0
(2026-09-28). Upstream continues to ship its own releases; this fork adopts
upstream changes one at a time, with credit, rather than merging wholesale.
The review of upstream's v0.4 and v0.5 features is in
docs/upstream-v0.5-draft.md, and every change is
in the CHANGELOG.
Issue | Problem | Fix in this fork | Upstream v0.6.0 |
Attachments only returned as base64 |
| Partly: a server-wide download folder on main, no per-call path | |
Sent mail never saved to Sent | IMAP APPEND into Sent after every send, on by default | Partly: opt-in, off by default | |
| Honoured | Fixed | |
No attachments on send | Attachments on send, forward and draft | Partly: | |
Memory leak in long-running process | Connections rotate every 30 minutes; caches evicted | Open (no rotation found; unverified) | |
Socket timeout crashes the process | Error and close handlers on every IMAP client | Fixed on main after v0.6.0 | |
Every call fails on llama.cpp models | Grammar-safe (GBNF) schemas | Fixed (via zod update) | |
Results ordered by UID | Ordered by date across the whole match set | Partly: only the current page is re-sorted | |
stdio server never exits | Exits when the client closes stdin; optional idle exit | Open | |
Retries send duplicates | Retried sends recognized and refused | Open | |
Raw MIME instead of the body | Decoded bodies; richer multipart part preferred | Fixed | |
Silent zero results on broken servers | A malformed (non-array) search reply fails loudly | Partly: the imapflow update avoids the Strato case | |
| Calendar writes and background services gated | Open | |
Non-ASCII draft subjects not encoded | Drafts built with MailComposer (RFC 2047) | Fixed | |
Replies stack "Re: RE:" and "Fwd: FW:" | Any case and common locales (AW, SV, WG) recognised | Open | |
Sent copy rejected by strict servers (bare LF) | Line endings normalised to CRLF before APPEND | Open |
Upstream status was read from upstream's source, not from whether the issue is closed: most of these issues are still open on GitHub even where the code has been fixed.
Plus fixes with no upstream issue: chunked UID fetches for large mailboxes,
visible login-failure reasons, STARTTLS reaching the IMAP client, OAuth2 in the
watcher, Bcc on send_draft, Reply-To on reply_email, and more. Security
hardening covers SMTP header injection, constant-time token checks, webhook SSRF
blocking, HTTPS-only OAuth endpoints, owner-only config files, and bounded HTTP
request bodies. See the CHANGELOG.
Development
pnpm install
pnpm check # Biome lint and format
pnpm typecheck
pnpm test # unit tests (588 across 68 files)
pnpm test:integration # against a throwaway GreenMail server (needs Docker)
pnpm smoke # every tool against a real configured accountpackage.json requires Node 24+. Contributions: see
CONTRIBUTING.md and the
Code of Conduct.
imap-wizard [command]
stdio Run as MCP server over stdio (default)
http Run as MCP server over Streamable HTTP
account list|add|edit|delete
setup Alias for 'account add'
test [account] Test IMAP and SMTP connections
install [status|remove] Register with MCP clients
config show|edit|validate|path|init
keychain status|migrate|remove
scheduler check|list|install|uninstall|status
list | read <id> | search <query> | mailboxes
flag <id> | delete <id> | attach <id> <file> | reply <id> | send
notify Test and diagnose desktop notifications
helpEmail commands take --account NAME (default: the first account). Read commands
support --json. delete asks for confirmation unless you pass --yes.
Credits
Built on email-mcp by @codefuturist. This fork also incorporates work from upstream contributors:
Contributor | Incorporated |
| |
Sender authentication signals, IMAP error handling, HTTP session lifecycle | |
Ported from upstream: the TLS servername repair
and config validate.
Thanks also to everyone who filed the upstream issues listed above.
License
LGPL-3.0-or-later, the same license as upstream.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to read, search, send, reply, forward, organize, schedule, and analyze email across multiple IMAP/SMTP accounts, with drafts, provider-aware labels, calendar extraction, verification-code catching, and a real-time inbox watcher. It runs over stdio or Streamable HTTP, with TLS, OAuth2, provider auto-detection, and a guided setup wizard.31 npmISC
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search and read email, inspect attachments, and optionally send messages and organize folders through existing IMAP and SMTP mailboxes. Supports Docker, stdio, and HTTPS OAuth deployment with read-only or full-access modes.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to read, search, send, reply, forward, schedule, and analyze email across multiple IMAP/SMTP accounts, with drafts, templates, provider-aware labels, bulk operations, attachment handling, calendar extraction, and real-time IMAP IDLE watching. Connections are secured with TLS/STARTTLS, OAuth2 support, and rate limiting, and it can run over stdio locally or Streamable HTTP for networked access.31 npmISC
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to read, search, send, schedule, manage, and analyze mail across multiple IMAP/SMTP accounts, including drafts, provider-aware labels, real-time IDLE triage, verification-code capture, and calendar extraction. Runs over stdio for local clients or Streamable HTTP for networked access, with a guided setup wizard and OAuth2 support.-