AnyMail MCP

AnyMail MCP

Connect all your email accounts to your AI agent — not just one.

AnyMail MCP is a local MCP server that gives anagent (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, …) full read /send / organize / delete access across multiple Gmail accounts at once, overIMAP/SMTP. Per-account App Passwords live in the macOS Keychain — nothing ishosted, and your credentials never leave your Mac.

Why AnyMail MCP exists

Today, connecting your mail to an AI agent generally means one account at atime — a single Gmail, or a single Microsoft 365 mailbox. But most people liveacross several inboxes: personal, work, a side project, an old address that stillgets the important stuff. The agent can only ever see one of them.

AnyMail MCP removes that limit. Connect every Gmail account you have, and your agentcan search, triage, draft, send, label, and clean up across all of them in asingle session — while every credential stays on your machine.

Multi-provider support (Microsoft 365 / Outlook, generic IMAP, iCloud) andOAuth sign-in are on the roadmap. v0.1.0 is Gmail + App Passwords.

What it can do

Full CRUD across every connected account:

Every tool takes an optional account (the email address); omit it to use yourdefault account.

Get started

AnyMail MCP runs two ways from one engine. Pick the track that fits you.

Prerequisite (every account, one-time)

1. Turn on 2-Step Verification on the Google account.
2. Create a 16-character App Password athttps://myaccount.google.com/apppasswords.(IMAP is always-on for Gmail — nothing else to toggle.)

An App Password grants full mailbox access and is stored only in yourKeychain. If a machine is lost, revoke it at the URL above — that instantlycuts AnyMail MCP off from that account. See SECURITY.md.

Track A — Command line (works today)

For developers and anyone comfortable in a terminal.

git clone https://github.com/MarcinWalendowski/anymail-mcp.git
cd anymail-mcp
npm install            # @napi-rs/keyring ships prebuilt binaries — no compiler needed
npm run build          # → dist/index.js

# add accounts (prompts for the App Password, hidden)
node dist/index.js add [email protected] --name "Personal" --default
node dist/index.js add [email protected]
node dist/index.js add [email protected] --read-only   # triage-only: refuses all writes
node dist/index.js list
node dist/index.js test [email protected]                  # verify IMAP + SMTP

# other providers (experimental — folder-based, limited search, no threads):
node dist/index.js add [email protected]   --provider icloud
node dist/index.js add [email protected] --provider fastmail
node dist/index.js add [email protected]     --provider imap --imap-host imap.host.tld --smtp-host smtp.host.tld

# register into every agent it can detect
node dist/index.js install

Tip: npm link once, then the commands are just anymail-mcp add …, anymail-mcp list, etc.

Track B — Menu-bar app (GUI)

For a no-terminal experience: a macOS menu-bar app that supervises the engine andgives you an Add Account window, an Install into Agents button, andStart at Login — the App Password never touches the app, it's posted once to127.0.0.1 and the engine stores it in the Keychain.

The source and build steps live in app/. Today you build ityourself (xcodegen generate + Xcode). A signed, notarized download that openswith a double-click is on the roadmap — the full plan (self-containedengine, DMG, notarization, CLI channels) is in DISTRIBUTION.md;notarizing needs an Apple Developer account, so it can't be produced here.

Connect it to your agent

node dist/index.js install writes the right config for each agent it detects:

Restart the agent afterward, then ask it to list_accounts.

Security model

The engine can read, send, and delete your mail, so the always-on server islocked down (full detail in SECURITY.md):

• Binds 127.0.0.1 only — never listens on the network.
• Bearer token on every request (engine + admin API), minted on first run andstored 0600 outside the repo. App Passwords never appear in any response.
• Origin validation — rejects browser origins (DNS-rebinding defense).
• App Passwords live only in the macOS Keychain.
• Per-account read-only mode; permanent delete requires confirm:true.
• Logs go to stderr with secret/body redaction.

Nothing secret is ever written into this repository — account config and theserver token live in ~/.gmail-mcp/ (outside the repo), passwords live in theKeychain.

Roadmap

• Generic IMAP providers — iCloud, Fastmail, and any IMAP host now work via--provider (experimental: folder-based, limited search, no threads).
• More providers — Microsoft 365 / Outlook (needs OAuth), Yahoo, so one agentspans every mailbox regardless of host.
• OAuth sign-in — connect an account with a normal "Sign in with Google /Microsoft" flow instead of manually creating App Passwords.
• One-click install — a signed & notarized DMG and a Homebrew cask sonon-technical users download and run without Gatekeeper warnings.
• npm/npx distribution for the CLI/engine.
• Windows & Linux engine builds (the engine is plain Node; the Keychainlayer is the only platform-specific piece).

How it works

Agent (Claude Code / Desktop / Cursor …)
   │  MCP over stdio or HTTP (127.0.0.1)
   ▼
AnyMail MCP engine  (local Node process)
   │  ImapFlow  → imap.gmail.com:993   (search, labels, threads, delete)
   │  Nodemailer→ smtp.gmail.com:465   (send, drafts)
   ▼
Gmail — authenticated per account with an App Password from the Keychain

Why IMAP/SMTP + App Passwords instead of the Gmail HTTP API: full-CRUD Gmail APIaccess needs restricted OAuth scopes, which for personal @gmail.com accountsforces Google app verification + an annual CASA security assessment (or a 7-daytoken expiry in Testing mode). App Passwords + IMAP sidestep all of it and runfine in a local process — and IMAP needs a long-lived TCP socket, so this can'tbe a serverless function anyway. See app/BUILD.md for themacOS app internals.

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. Release processis in RELEASING.md.

License

MIT © Marcin Walendowski