imap-mcp

A Model Context Protocol (MCP) server for any IMAP mailbox. It speaks IMAP rather than one vendor's API, so it works with whatever provider you already have.

Lets MCP clients like Claude Code, Claude Desktop or Codex read and search your mail, organise it into folders, save attachments and draft replies — with every message fenced as untrusted content, and the write tools off unless you turn them on.

Eleven tools, not fifty: a mail account is a workflow, not an API surface, so related operations are folded into one tool with a mode rather than split across many. And eleven is the ceiling, not the floor — IMAP_ALLOW_TOOLS=essential registers a curated six instead, and under the read-only default that narrows to four. See choosing which tools load.

What makes it different

It cannot send mail. That is the feature. An agent with access to private data, exposure to untrusted content, and a channel to the outside world is exploitable by anyone who can put a message in the inbox — the pattern that produced EchoLeak, where one crafted email exfiltrated internal data from Microsoft 365 Copilot with no user interaction. This server has the first two and deliberately not the third. save_draft writes the reply into your Drafts folder; you send it from your own mail client. No amount of clever text in a message can make this server post anything anywhere.

Writes are off until you turn them on. With only IMAP_HOST, IMAP_USER and IMAP_PASSWORD set, the server registers six read tools and nothing else. The mailbox tools appear with IMAP_READ_ONLY=false — note the default is true, the opposite of the other servers in this family, because this one reaches a mailbox. Tools that are off are not registered at all — a capability the model cannot see is one it cannot be talked into using.

Mail is treated as hostile input, because it is. Anyone in the world can put text in your inbox. Message bodies are fenced between markers carrying a per-call random nonce, and every line inside them is prefixed with that nonce, so the "this is data" signal does not stop at the edges of a long forwarded thread. A reminder follows the block, because otherwise the last instruction-shaped sentence in the model's context is the attacker's. Zero-width characters and directional overrides are stripped before the model sees anything, hidden HTML elements are dropped on a best-effort basis (the fencing, not the stripping, is what carries the weight), and markdown image syntax — inline and reference style — is defused so a rendering client cannot be made to fetch a tracking URL.

Alongside the message you get a server-side assessment: the SPF/DKIM/DMARC verdicts with the authserv-id they came from, which prompt-injection shapes matched, and which words mix Latin with Cyrillic or Greek letters. When something matches, the warning is the first thing in the result rather than a field buried in JSON.

Those verdicts carry a forgeable flag, and by default it is always true. A sender can write an Authentication-Results header of their own, and if your provider does not add one, theirs is the only one there — nothing inside the message distinguishes the two. Set IMAP_TRUSTED_AUTHSERV_ID to the id your provider stamps (it is the first token of the header on any message you already have) and only that id counts as authentic. Until you do, spf=pass is reported as what it is: a claim, from a header anyone could have written.

"New mail" that actually works. The server tags messages it has handed over with a custom IMAP keyword (AiSeen by default), so list_new_messages returns each message once. The human \Seen state is never touched — everything is read with BODY.PEEK.

Deleting asks a person. Where the client supports MCP elicitation, delete_messages and deleting a folder raise a real dialog that the model cannot answer on its behalf. Where it does not, they fall back to a two-call token — and say so, rather than implying somebody approved.

Related MCP server: Mac Local Mail MCP

Requirements

• Node.js 22 or newer

• An IMAP account. Providers with two-factor authentication generally need an app-specific password.

Configuration

Booleans are compared against the literal string true; 1, yes and True are not true. IMAP_READ_ONLY is the mirror image: only the literal false turns it off, so a typo leaves the write tools unregistered.

IMAP_ALLOW_WRITE is gone. It has been replaced by IMAP_READ_ONLY, and an installation that still sets it refuses to start. Silently ignoring a removed security variable is the worst of the options: whoever set it once believes it is still in force. The default is unchanged — writes are still off unless you ask for them.

Choosing which tools load

IMAP_ALLOW_TOOLS and IMAP_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset of six — list_mailboxes, list_new_messages, list_messages, get_message, set_message_flags and move_messages. Four of those are read tools, so it stays useful under the read-only default.

IMAP_ALLOW_TOOLS=essential
IMAP_ALLOW_TOOLS=list_new_messages,get_message,move_messages
IMAP_DENY_TOOLS=delete_messages

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under IMAP_READ_ONLY.

It covers tools. The attachment resources this server also exposes are not filtered.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools. The password is deleted from the process environment as soon as it is read, so it is not visible to child processes or in /proc/<pid>/environ.

Without IMAP_DOWNLOAD_DIR this server never writes to the filesystem. The two size limits are separate on purpose: one protects the model's context window, the other protects your disk.

The server starts without credentials on purpose — it completes the handshake and lists its tools, and every call then fails with setup instructions instead of reaching a server.

Installation

Claude Code

claude mcp add imap-mcp \
  -e IMAP_HOST=imap.example.net -e IMAP_USER=you@example.net -e IMAP_PASSWORD=… \
  -- npx -y @ni-c/imap-mcp

Claude Desktop

{
  "mcpServers": {
    "imap-mcp": {
      "command": "npx",
      "args": ["-y", "@ni-c/imap-mcp"],
      "env": {
        "IMAP_HOST": "imap.example.net",
        "IMAP_USER": "you@example.net",
        "IMAP_PASSWORD": "…"
      }
    }
  }
}

Codex

[mcp_servers.imap-mcp]
command = "npx"
args = ["-y", "@ni-c/imap-mcp"]
env = { IMAP_HOST = "imap.example.net", IMAP_USER = "you@example.net", IMAP_PASSWORD = "…" }

Docker

docker run --rm -i \
  -e IMAP_HOST=imap.example.net \
  -e IMAP_USER=you@example.net \
  -e IMAP_PASSWORD=… \
  ghcr.io/ni-c/imap-mcp

Saving attachments needs a writable directory, and the image runs as uid 1000 — so a bind mount has to be owned by it on the host: -e IMAP_DOWNLOAD_DIR=/data -v "$PWD/attachments:/data" with chown 1000:1000 attachments. Without IMAP_DOWNLOAD_DIR the container never writes anything.

Tools

Read — always registered

Mailbox — needs IMAP_READ_ONLY=false

👤 raises a dialog the model cannot answer · 🔒 needs a confirmation token: call once to receive one, then again with it.

copy is confirmed as well as move, because the thing that cannot be taken back is not the deletion — it is the disclosure. A destination is a free-form folder name, and on a shared account or a public namespace one call hands every message to everyone who can read it, leaving the source folder untouched. For the same reason set_message_flags refuses to add \Deleted: it is half a deletion, and the next client to close the mailbox may finish it. Use delete_messages, which asks.

Neither a confirmation nor a dialog quotes a mailbox name inside its own sentence — folder names come from the account, which on a shared mailbox means a colleague chose them.

Attachments are also available as MCP resources at imap://message/{uid}/part/{partId}, which matters where the server has no useful filesystem. The resource path runs the same allowlist, size limit and magic-byte check as the tool — it is not a second, unguarded door.

Not exposed, on purpose

No sending, no SMTP, no raw IMAP passthrough, no APPEND of arbitrary MIME, no HTML composition, no OAuth2. The first is the whole security argument (see SECURITY.md); the second would make every guard here optional; the last is planned but needs a test account before it ships.

And one thing the tool filter does not cover: attachment resources. IMAP_ALLOW_TOOLS narrows tools/list, not resources/list, so a server with a narrow allow list still serves those. IMAP_DOWNLOAD_DIR and the content-type allowlist are what constrain them — worth knowing before concluding that a filtered install reaches less of the mailbox than it does.

Safety

• Every result carrying mailbox content is marked untrusted, message bodies additionally fenced with a per-call nonce and marked line by line.

• Attachments pass two independent gates. The declaration is checked against a content-type allowlist, an executable-extension refusal list and a size ceiling; the bytes are then checked against magic numbers. An executable renamed to .pdf and declared application/pdf clears every declaration check and fails on its bytes — including when saving to disk, where it would be more dangerous, not less.

• A part_id must come from a listing call, so the body cannot be pulled out through the attachment tool and escape its framing.

• Downloads cannot escape their directory. The target comes only from the environment, the filename is sanitised, the resolved path is re-checked, and the file is opened with wx and mode 0600 — so nothing is overwritten and no planted symlink is followed.

• Mailbox names, flags and addresses are refused if they contain line breaks. IMAP is a line protocol and a draft is a mail header; a CR is an injection primitive, not a typo.

• TLS is never disabled globally. IMAP_INSECURE_TLS is scoped to the connection it names; NODE_TLS_REJECT_UNAUTHORIZED appears nowhere.

• Every change to the mailbox is logged to stderr with the UIDs and folder — never the subject. stderr is the one channel the model does not read.

• Responses are bounded. Whole items are dropped rather than the JSON being sliced, and the truncation notice comes first so the recovery hint survives.

SECURITY.md has the trust model, what these measures do not cover, and how to report a vulnerability.

Development

npm install
npm test
npm run build

The test suite runs against an in-memory IMAP fake, so it needs no server and no network. For a live server to point the real thing at, see CONTRIBUTING.md — it starts a throwaway mailbox in a container.

Releasing

1. Add the CHANGELOG entry and bump package.json.

2. npm run lint && npm run build && npm run test:coverage

3. Commit, then push a signed tag: git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin main vX.Y.Z

The release workflow publishes to npm (Trusted Publishing, with provenance), creates the GitHub release from the CHANGELOG section and updates the MCP Registry entry.

License

MIT © Willi Thiel