imail-mcp

🇷🇺 Документация на русском: README.ru.md

An MCP server that connects Claude (Cowork / Claude Code / Claude Desktop) to your email so it can read, search, send, and organize your mail — directly from a conversation.

Runs as a resident background service (launchd) with a web admin UI, serving all your Claude clients over one Streamable HTTP endpoint — or as a classic per-client stdio server. iCloud Mail is the first supported provider; the internals are written against a provider-agnostic interface, so Gmail / Microsoft 365 adapters can be added later without touching a single tool.

Highlights

• 🖥️ Runs as a service — one long-lived process (launchd LaunchAgent, auto-start at login, auto-restart) shared by every MCP client over Streamable HTTP; stdio mode still works for per-client setups.

• 🌐 Web admin UI — connect/disconnect Apple accounts, check live connection status, copy ready-made client configs, tail the service log — all at http://127.0.0.1:4577, localhost-only.

• 👥 Multiple accounts — connect several iCloud accounts; every tool takes an optional account parameter.

• 📥 Read & search — folders, search with paging, full messages and whole threads, bulk fetch up to 20 full messages per call, attachments.

• ✉️ Send & reply — compose, reply, reply-all, forward with correct threading headers.

• 🗂️ Organize, in bulk — move / archive / delete / flag up to 200 messages per call as a single IMAP command.

• 🔒 Credentials stay local — account passwords and the service's access token live in the macOS Keychain, never in a plaintext file or env var.

• 🛑 Never sends silently — Claude must preview an email and get your approval first; on clients that support MCP elicitation, the server additionally asks you to confirm in-app before anything is sent.

Related MCP server: macos-mail-mcp

The Mac app

The nicest way to run imail-mcp is the menu-bar app in app/: a signed, notarizable iMail MCP.app that bundles the whole service as a self-contained binary (no Node required), shows live status in the menu bar, opens the control panel in its own window, and starts at login. Build it with cd app && npm install && npm run tauri build, then drag the .app from app/src-tauri/target/release/bundle/macos/ into /Applications. On first launch it takes over from the CLI-installed launchd service automatically.

Everything below — the CLI service, stdio mode, tools, security model — works the same with or without the app; the app is just a shell that owns the service process.

Quick start (CLI, no app)

Requires Node.js ≥ 18 and macOS.

git clone git@github.com:nurked/icloud-mail-mcp.git
cd icloud-mail-mcp
npm install
npm run build
node dist/index.js service install   # register + start the background service
node dist/index.js ui                # open the admin UI in your browser

In the admin UI:

1. Accounts tab — connect your iCloud account (see the app-specific password note below). The login is verified live over IMAP, then stored in your Keychain.

2. Clients tab — copy the ready-made one-liner for Claude Code, or the JSON block for Claude Desktop. Done.

Installing globally (npm link or npm i -g .) gives you the imail-mcp command used in the examples below; otherwise use node dist/index.js <command>.

CLI reference

imail-mcp                      stdio MCP server (for per-client mcpServers configs)
imail-mcp serve [--port N]     run the HTTP service in the foreground
imail-mcp ui                   open the admin UI (authenticated) in your browser
imail-mcp service install      install + start the launchd LaunchAgent
imail-mcp service status       show whether the service is installed/running
imail-mcp service uninstall    stop and remove the LaunchAgent

Default port: 4577. Logs: ~/Library/Logs/imail-mcp/imail-mcp.log.

Generating the app-specific password

Apple does not offer OAuth for iCloud Mail — the only supported path is IMAP/SMTP with an app-specific password (every iCloud account has 2FA):

1. Open appleid.apple.com → Sign-In and Security → App-Specific Passwords.

2. Click Generate an app-specific password, name it imail-mcp.

3. Paste the 16-character password into the admin UI.

Wire it into Claude

Preferred — the shared service (copy the exact command, with your token filled in, from the admin UI's Clients tab):

claude mcp add --transport http imail http://127.0.0.1:4577/mcp \
  --header "Authorization: Bearer <token>"

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "imail": {
      "type": "http",
      "url": "http://127.0.0.1:4577/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Fallback — per-client stdio (each client spawns its own process; no service needed):

{
  "mcpServers": {
    "imail": { "command": "node", "args": ["/absolute/path/to/dist/index.js"] }
  }
}

Security model

• The HTTP service binds to 127.0.0.1 only and validates the Host header (DNS-rebinding protection, plus the MCP SDK's own check).

• The /mcp endpoint requires a bearer token, generated on first run and stored in the Keychain — without it, other local processes can't read or send your mail through the service.

• The admin UI uses a one-time token URL (imail-mcp ui) exchanged for an HttpOnly, SameSite=Strict session cookie; mutating API calls additionally require a custom header (CSRF).

• Sending tools are gated three ways: prompt discipline (preview first), tool annotations (destructiveHint on sends/deletes), and elicitation — on supporting clients the server asks you to confirm each send in-app, and a declined confirmation returns sent: false.

Tools

Every tool takes an optional account parameter (omit when only one account is connected). Bulk operations execute as a single IMAP command (UID set), not N round-trips. All tools declare MCP tool annotations (read-only / destructive / idempotent hints) and output schemas (structured content), per the 2025-06-18+ MCP spec.

How it works

Claude Code ─┐
Claude Desktop ─┤  Streamable HTTP (127.0.0.1:4577/mcp, bearer token)
Cowork ─┘        │
                 ▼
      imail-mcp service (launchd)  ──IMAP (imap.mail.me.com:993)──▶  iCloud
        │  admin UI at /           └─SMTP (smtp.mail.me.com:587)──▶  iCloud
        └─ credentials + token ◀── macOS Keychain
           account registry     ◀── ~/Library/Application Support/imail-mcp/

• IMAP (imapflow) reads and organizes; SMTP (nodemailer) sends; bodies are parsed with mailparser.

• A shared provider pool keeps one live IMAP connection per account, with keepalive and transparent reconnect (dead sockets retry once).

• Connections are lazy — adding the server to Claude doesn't touch your mailbox until you actually use it.

• Built on MCP SDK 1.x (spec line 2025-06-18 / 2025-11-25). The transport layer is isolated in src/http/, so migrating to the stateless 2026-07-28 spec / SDK v2 is a contained change.

Project layout

src/
  index.ts              CLI: stdio server, serve, ui, service subcommands
  mcp.ts                MCP server factory: tools, schemas, annotations, elicitation
  bin/setup.ts          `imail-mcp-setup` — foreground service + admin UI (legacy entry)
  accounts/
    registry.ts         non-secret account registry (accounts.json)
    pool.ts             provider pool: lazy connect, keepalive, add/remove accounts
  auth/
    keychain.ts         Keychain storage: per-account credentials + HTTP token
  http/
    server.ts           HTTP service: /mcp (session map), /auth, /api, admin UI
    ui.ts               admin UI page (no framework, no build step)
  service/
    launchd.ts          LaunchAgent install/uninstall/status
  providers/
    types.ts            provider-agnostic MailProvider contract
    icloud.ts           iCloud IMAP/SMTP implementation (incl. bulk ops)

Adding another provider

The tools only ever talk to the MailProvider interface, so a new backend is one new file:

1. Implement MailProvider (see src/providers/types.ts) in a new file under src/providers/.

2. Wire it up in src/accounts/pool.ts.

The tools stay unchanged.

Troubleshooting

• "No mail accounts are connected" — open the admin UI (imail-mcp ui) and connect an account on the Accounts tab.

• "Login failed" when connecting — make sure you used an app-specific password, not your normal Apple ID password.

• imail-mcp ui says the service isn't answering — start it: imail-mcp service install (persistent) or imail-mcp serve (foreground).

• Port already in use — pass --port N to serve / service install, and update your client configs accordingly.

• Upgrading from ≤0.1 — the old single-account Keychain entry is migrated automatically on first run; existing stdio client configs keep working.

• Service logs — ~/Library/Logs/imail-mcp/imail-mcp.log (also shown in the admin UI's Service tab).

License

PolyForm Noncommercial License 1.0.0 — this is source-available, not OSI open source.

• ✅ Free for any noncommercial purpose — personal use, study, research, hobby projects, and use by nonprofits, schools, and government bodies.

• ✅ You may read, modify, and redistribute it; the copyright notice must stay intact, so your work is always credited.

• 💼 Commercial use requires a separate license. If you want to use imail-mcp to make money — in a product, a paid service, or inside a for-profit company — contact Investment Fidelity Company at ceo@investmentfidelity.company to arrange a commercial license.

See LICENSE.md for the full terms.