Skip to main content
Glama
IMAP Wizard

IMAP Wizard

by Fe2-O3

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.

release License: LGPL v3 tests Node.js 24+ MCP SDK v2

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 clients

Or add it to a client by hand. Claude Code:

claude mcp add email -- npx -y imap-wizard stdio

Claude 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 add

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

NOTE

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?"

list_emails, sorted by date

"Find the Acme invoice from this month and save the PDF to my Downloads folder"

search_emails, get_email, download_attachment with savePath

"Reply to that thread: Thursday works, cc billing"

reply_email (honours Reply-To, files the reply into Sent)

"Is this sender legit?"

get_email_security (DMARC, SPF, DKIM results from the headers)

"Triage my inbox and skip the newsletters"

triage_inbox prompt, plus bulk-mail flags read from headers

"Move last month's receipts into Receipts"

search_emails, then bulk_action


Why this one

  • Bugs fixed that upstream still has. As of upstream v0.6.0: duplicate sends on retry, read_only not 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_email fetches with IMAP BODY.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, a password_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

get_email uses BODY.PEEK; marking read is an explicit markRead: true

read_only

off

Hides every write tool and stops background services. markRead is refused

Send rate limit

10 per minute per account

settings.rate_limit

Audit log

on

Writes are logged, with sensitive fields redacted, to ~/.local/share/email-mcp/audit.log

Duplicate-send guard

on

A retried send is recognized and refused unless you pass allow_duplicate

HTTP transport token

required

http mode generates a bearer token, even on loopback

Verification-code tool

off

get_verification_code is only registered when you enable it; it never reads your clipboard

Body cache (read_through)

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

list_accounts list_mailboxes list_emails search_emails get_email get_emails get_email_status get_thread download_attachment find_email_folder extract_contacts get_email_stats get_email_security check_health list_templates

Calendar (read)

extract_calendar analyze_email_for_scheduling list_calendars list_events list_reminders check_calendar_permissions

Watcher (read)

get_watcher_status list_presets get_hooks_config check_notification_setup

Send (write)

send_email reply_email forward_email save_draft send_draft apply_template

Schedule (write)

schedule_email list_scheduled cancel_scheduled

Organize (write)

move_email delete_email mark_email bulk_action create_mailbox rename_mailbox delete_mailbox

Labels (write)

list_labels add_label remove_label create_label delete_label

Calendar and alerts (write)

add_to_calendar create_reminder configure_alerts test_notification

Opt-in

get_verification_code (needs settings.verification.enabled = true)

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 = true

Check 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 uses secret-tool (libsecret). node dist/main.js keychain migrate moves existing plaintext passwords over.

  • Password command: password_command = "op read 'op://Private/mail/password'" (or bw get password ..., pass show ...). It runs once at startup, must print the password to stdout, and is killed after 10 seconds. It wins over password if both are set.

  • OAuth2: an [accounts.oauth2] block instead of a password.

  • Plaintext: allowed, written readable only by you. config show masks 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

settings.idle_exit

0 (off)

Seconds without a request before the stdio server exits. A backstop for clients that never close the pipe

settings.send.max_attachment_mb

25

Cap on attachments per message. Known providers may lower it; an account-level max_attachment_mb overrides

settings.cache.enabled

true

Local header-and-flags mirror (mailboxes = ["INBOX"], window_days = 90, max_size_mb = 500)

settings.watcher.enabled

false

IMAP IDLE watcher for new mail, with optional hooks and alerts

settings.verification.enabled

false

Registers get_verification_code

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 8080

On 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

MCP error -32001: Request timed out

Your client stops waiting after 60 s; a full-text search on a huge mailbox can take longer

Raise the client timeout (180000 in OpenCode)

Setup says the config file is invalid

A TOML syntax or key error

node dist/main.js config validate names the line and key

Login fails

Wrong password, or the provider needs an app password

The error now shows the server's own reason; run node dist/main.js test

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 settings.idle_exit = 1800, or close the client cleanly

Cannot find module .../nodemailer/... after an update

The old server process is still running

Restart your client (in Claude Code: /mcp, then reconnect)


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

#12

Attachments only returned as base64

savePath writes to disk and returns path, size and SHA-256

Partly: a server-wide download folder on main, no per-call path

#20 #54 #92

Sent mail never saved to Sent

IMAP APPEND into Sent after every send, on by default

Partly: opt-in, off by default

#45

forward_email ignores html

Honoured

Fixed

#52

No attachments on send

Attachments on send, forward and draft

Partly: send_draft still drops them

#55

Memory leak in long-running process

Connections rotate every 30 minutes; caches evicted

Open (no rotation found; unverified)

#57

Socket timeout crashes the process

Error and close handlers on every IMAP client

Fixed on main after v0.6.0

#58

Every call fails on llama.cpp models

Grammar-safe (GBNF) schemas

Fixed (via zod update)

#59

Results ordered by UID

Ordered by date across the whole match set

Partly: only the current page is re-sorted

#60

stdio server never exits

Exits when the client closes stdin; optional idle exit

Open

#62

Retries send duplicates

Retried sends recognized and refused

Open

#66 #95

Raw MIME instead of the body

Decoded bodies; richer multipart part preferred

Fixed

#71 #91

Silent zero results on broken servers

A malformed (non-array) search reply fails loudly

Partly: the imapflow update avoids the Strato case

#79

read_only does not gate background work

Calendar writes and background services gated

Open

#96

Non-ASCII draft subjects not encoded

Drafts built with MailComposer (RFC 2047)

Fixed

#102

Replies stack "Re: RE:" and "Fwd: FW:"

Any case and common locales (AW, SV, WG) recognised

Open

#116

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 account

package.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
  help

Email 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:

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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      ISC
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      ISC
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -