Mail MCP

An MCP server for any IMAP mailbox — Gmail, Outlook, iCloud, Fastmail, Yandex, your company's own server. Not tied to a provider, an account or a project: it is configured with the host, the address and the password, and that is the whole binding.

20 tools covering reading, searching, threading, sending, replying, forwarding, drafts, flags, folders and attachments.

The headline feature: the server reads attachments. A screenshot mailed to you is downloaded and handed to the model as an image — not as a filename it cannot open.

Two ways to run it

Mail is not a scoped API token: the password usually opens the whole mailbox, and often the account behind it. Running locally is therefore the recommended mode, and the hosted endpoint exists for the cases where that is not practical — see Hosted mode for what that choice actually costs.

git clone git@github.com:amalychev/mail-mcp.git
cd mail-mcp
npm install
npm run build

Requires Node.js 20 or newer.

Connecting from Claude Code

claude mcp add mail \
  --env MAIL_USER=you@fastmail.com \
  --env MAIL_PASSWORD=your-app-password \
  -- node /absolute/path/mail-mcp/dist/index.js

That is the whole setup for a known provider: the IMAP and SMTP hosts are derived from the address. Ask for mail_whoami to confirm — it logs in to both servers and reports what it found.

Or drop a .mcp.json into the root of your working repository:

{
  "mcpServers": {
    "mail": {
      "command": "node",
      "args": ["/absolute/path/mail-mcp/dist/index.js"],
      "env": {
        "MAIL_USER": "you@example.com",
        "MAIL_PASSWORD": "${MAIL_PASSWORD}",
        "IMAP_HOST": "imap.example.com",
        "SMTP_HOST": "smtp.example.com"
      }
    }
  }
}

The same block works in Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json). Write "${MAIL_PASSWORD}" rather than the password itself — Claude Code and Cursor substitute environment variables, so the file stays shareable and the secret stays in your shell.

Several mailboxes at once — several entries with different names:

{
  "mcpServers": {
    "mail-work":     { "command": "node", "args": ["…/dist/index.js"], "env": { "MAIL_USER": "me@company.com", "MAIL_PASSWORD": "…" } },
    "mail-personal": { "command": "node", "args": ["…/dist/index.js"], "env": { "MAIL_USER": "me@fastmail.com", "MAIL_PASSWORD": "…" } }
  }
}

Two things worth knowing when a change appears to do nothing:

• In Claude Code an entry added to the local scope (kept in ~/.claude.json) takes precedence over the project's .mcp.json. claude mcp list shows what is actually in use, and claude mcp remove <name> -s local drops a stale one.

• Client configuration is read at startup, so restart the app after editing the file.

Related MCP server: io.github.p-w-4-z/inbox-mcp

The password

Nearly every provider refuses your account password over IMAP and wants an app-specific password — a separate value you generate once, use here, and can revoke without touching the account itself.

Microsoft has switched personal accounts and most tenants to OAuth, so a password often fails outright. Supply an access token as MAIL_PASSWORD together with MAIL_AUTH_TYPE=oauth2; the same setting works for Gmail's OAuth if you prefer it to an app password.

When authentication fails, the error names your provider and says what it wants — the message is not a generic "login failed".

Configuration

In stdio mode everything is configured through environment variables.

MAIL_ADDRESS, MAIL_PASS, IMAP_USER, IMAP_PASSWORD, MAIL_IMAP_HOST and MAIL_SMTP_HOST are accepted as aliases.

Providers with a preset

gmail, outlook, yahoo, icloud, fastmail, zoho, yandex, mailru, gmx, aol, migadu, mailbox, proton — each fills in the IMAP and SMTP host, port and transport. Aliases such as google, hotmail, office365 and protonmail resolve to the right one, and an address ending in a domain the preset owns selects it with no configuration at all.

Anything else is a normal IMAP server: give the two hosts and it works.

What the tools do

Messages are addressed by UID within a folder. A UID is only meaningful together with the folder it came from, and a message that moves gets a new one — every tool that returns messages returns the folder alongside them.

Folders accept aliases: inbox, sent, drafts, trash, junk, archive resolve through the server's own special-use flags, so they work whether the account calls it Sent, [Gmail]/Sent Mail or Отправленные.

Reading

mail_read_message fetches only the body part, so a message carrying a 20 MB attachment still costs a few kilobytes to read. HTML-only mail is flattened to prose with the links kept. Reading never marks anything as read unless you pass mark_read: true.

Attachments

Writing

Every sent message is filed in the Sent folder, and the copy is the exact bytes that were sent rather than a re-composed lookalike. The From address comes from the deployment and cannot be overridden by a tool argument.

Organising

Keeping it inside bounds

An assistant with a mailbox password can, in principle, read everything and write to anyone. Three independent limits narrow that, and they stack:

Read-only. MAIL_READ_ONLY=true refuses every tool that sends, moves, flags or deletes. Reading still works completely.

A recipient allowlist. MAIL_ALLOWED_RECIPIENTS=@yourcompany.com,partner@client.com checks every recipient — To, Cc and Bcc together — before anything reaches the SMTP server. This is the one worth setting even when everything else is open: it turns "the assistant could email anyone" into "the assistant could email these people".

A folder allowlist. MAIL_ALLOWED_FOLDERS=INBOX,INBOX/Clients puts every other folder out of reach, for reading as well as writing. A listed folder covers its subfolders. The "no such folder" error is filtered to the allowed set, so it cannot be used to map the account.

Beyond that: deleting is a move to Trash unless permanent: true and confirm: true are both given, deleting a folder needs confirm: true, and an app-specific password can be revoked in the provider's interface without touching the account.

Hosted mode

Start the HTTP transport with MCP_TRANSPORT=http (or --http). It serves:

Every request carries its own credentials, so one deployment serves many mailboxes without holding state:

TLS verification, timeouts and the size caps are deliberately not header-controlled: they are process-wide and belong to whoever runs the deployment. Attaching files from disk is forced off, because in hosted mode "the local disk" is the server's, not the caller's.

Without an allowlist the server refuses private addresses (localhost, RFC 1918 ranges, 169.254.*, *.internal, *.local) so a public deployment cannot be used to probe the network it runs in. MAIL_ALLOWED_HOSTS=imap.example.com,smtp.example.com narrows it to named hosts.

docker build -t mail-mcp .
docker run -p 8080:8080 -e MAIL_ALLOWED_HOSTS=imap.example.com,smtp.example.com mail-mcp

What hosting costs you. The mailbox password passes through the host on every request. The server keeps nothing — no accounts, no database, nothing written to disk, one throwaway server instance per request — but a mailbox password is not a scoped token, and no amount of "we store nothing" changes that. Run it yourself, or run it locally over stdio, whenever that matters.

Connection reuse

Logging in to IMAP costs a TLS handshake and a round trip, and providers rate-limit repeated logins hard. Authenticated connections are therefore pooled per mailbox and kept warm for five idle minutes, shared across requests in hosted mode. Work on one connection is serialised, because a single IMAP connection has one selected folder at a time.

Deploying

deploy.sh does the whole cycle on the server — pull, build, swap the container, verify, purge the CDN cache:

./deploy.sh                # the usual deploy
./deploy.sh --page-only    # only replace landing.html in the running container, no rebuild
./deploy.sh --no-pull      # deploy the working tree as it is
./deploy.sh --logs         # follow the container log afterwards

Copy deploy.env.example to deploy.env on the server and set the port, container name, PUBLIC_URL and, if the site sits behind Cloudflare, a zone id and an API token with the Cache Purge permission. deploy.env is git-ignored, so server-specific values stay there.

The previous image is tagged :previous before every build, and a failed health check restores it automatically and exits non-zero, so a broken build never stays deployed.

Landing page assets

assets/ holds everything the page references: favicon.svg (the source of every raster icon), favicon.ico, the touch and PWA icons, site.webmanifest, and og-image.png — the 1200×630 preview, rendered from assets/og-card.html.

The PNG and ICO files are committed, so a normal build needs nothing extra. Regenerate them only after editing favicon.svg or og-card.html:

npm run assets      # headless Chrome does the rasterising; set CHROME=… if it is not found

Development

npm run build       # compile
npm run dev         # tsc --watch
npm run typecheck   # types only
npm run start       # stdio mode
npm run start:http  # hosted mode on PORT (default 8080)

Layout:

src/
  index.ts          entry point, picks stdio or HTTP
  server.ts         builds a configured MCP server with every tool registered
  http.ts           hosted mode: landing page, stateless /mcp, per-request credentials
  config.ts         configuration from environment or headers
  providers.ts      host presets for the common mail services
  mail-client.ts    IMAP connection pool, folder resolution, bodies, attachments, SMTP
  mime.ts           charsets, HTML to text, addresses, quoting, subjects
  dates.ts          date arguments: ISO, `7d`, `yesterday`
  tools/
    helpers.ts      shared argument schemas, result formatting, the read-only guard
    core.ts         mail_whoami
    folders.ts      folder tree and management
    messages.ts     listing, search, reading, threads, raw source
    attachments.ts  attachment listing and download
    compose.ts      send, reply, forward, drafts
    actions.ts      flags, moving, copying, deleting

To add a tool, call defineTool in the appropriate module: error handling and the read-only guard are wired in automatically.

Troubleshooting

A visual walkthrough with examples lives in landing.html at the repository root.