{
"markdown": "# imap-mcp\n\n\n\n[](https://github.com/ni-c/imap-mcp/actions/workflows/ci.yml)\n[](https://scorecard.dev/viewer/?uri=github.com/ni-c/imap-mcp)\n![\"Socket](\"https://socket.dev/api/badge/npm/package/@ni-c/imap-mcp\")
\n[](https://glama.ai/mcp/servers/ni-c/imap-mcp)\n
\n[](https://www.npmjs.com/package/@ni-c/imap-mcp)\n[](https://github.com/ni-c/imap-mcp/pkgs/container/imap-mcp)\n[](https://mcp-hub.ni-c.de)\n
\n[](https://imap-mcp.ni-c.de)\n[](https://github.com/sponsors/ni-c)\n\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for any IMAP\nmailbox. It speaks IMAP rather than one vendor's API, so it works with whatever provider you\nalready have.\n\nLets MCP clients like Claude Code, Claude Desktop or Codex read and search your mail, organise\nit into folders, save attachments and draft replies — with every message fenced as untrusted\ncontent, and the write tools off unless you turn them on.\n\nEleven tools, not fifty: a mail account is a workflow, not an API surface, so related\noperations are folded into one tool with a mode rather than split across many. And eleven is\nthe ceiling, not the floor — `IMAP_ALLOW_TOOLS=essential` registers a curated six instead, and\nunder the read-only default that narrows to four. See\n[choosing which tools load](#choosing-which-tools-load).\n\n\n\n \n \n ![\"An](\"https://imap-mcp.ni-c.de/architecture.svg\")
\n\n\n![\"Listing](\"https://imap-mcp.ni-c.de/demo.gif\")
\n\n## What makes it different\n\n**It cannot send mail. That is the feature.** An agent with access to private data, exposure to\nuntrusted content, and a channel to the outside world is exploitable by anyone who can put a\nmessage in the inbox — the pattern that produced\n[EchoLeak](https://msrc.microsoft.com/update-guide/vulnerability/CVE-2025-32711), where one\ncrafted email exfiltrated internal data from Microsoft 365 Copilot with no user interaction.\nThis server has the first two and deliberately not the third. `save_draft` writes the reply\ninto your Drafts folder; you send it from your own mail client. No amount of clever text in a\nmessage can make this server post anything anywhere.\n\n**Writes are off until you turn them on.** With only `IMAP_HOST`, `IMAP_USER` and\n`IMAP_PASSWORD` set, the server registers six read tools and nothing else. The mailbox tools\nappear with `IMAP_READ_ONLY=false` — note the default is `true`, the opposite of the other\nservers in this family, because this one reaches a mailbox. Tools that are off are not registered at all — a\ncapability the model cannot see is one it cannot be talked into using.\n\n**Mail is treated as hostile input, because it is.** Anyone in the world can put text in your\ninbox. Message bodies are fenced between markers carrying a per-call random nonce, _and_ every\nline inside them is prefixed with that nonce, so the \"this is data\" signal does not stop at the\nedges of a long forwarded thread. A reminder follows the block, because otherwise the last\ninstruction-shaped sentence in the model's context is the attacker's. Zero-width characters and\ndirectional overrides are stripped before the model sees anything, hidden HTML elements are\ndropped on a best-effort basis (the fencing, not the stripping, is what carries the weight), and\nmarkdown image syntax — inline and reference style — is defused so a rendering client cannot be\nmade to fetch a tracking URL.\n\nThat covers folder names too, and it did not always: a folder name is chosen by whoever created\nthe folder, which on a shared mailbox is not necessarily you. `list_mailboxes` returns the name\ntwice — `path` exactly as the server spelled it, because that is the handle every other tool\ntakes, and `display_name` cleaned up for reading, with a warning on the entry when the two differ.\n\nAlongside the message you get a server-side assessment: the SPF/DKIM/DMARC verdicts with the\nauthserv-id they came from, which prompt-injection shapes matched, and which words mix Latin\nwith Cyrillic or Greek letters. When something matches, the warning is the first thing in the\nresult rather than a field buried in JSON.\n\nThose verdicts carry a `forgeable` flag, and by default it is always `true`. A sender can write\nan `Authentication-Results` header of their own, and if your provider does not add one, theirs\nis the only one there — nothing inside the message distinguishes the two. Set\n`IMAP_TRUSTED_AUTHSERV_ID` to the id your provider stamps (it is the first token of the header\non any message you already have) and only that id counts as authentic. Until you do, `spf=pass`\nis reported as what it is: a claim, from a header anyone could have written.\n\n**\"New mail\" that actually works.** The server tags messages it has handed over with a custom\nIMAP keyword (`AiSeen` by default), so `list_new_messages` returns each message once. The human\n`\\Seen` state is never touched — everything is read with `BODY.PEEK`.\n\n**Deleting and moving ask a person.** Where the client supports MCP elicitation, `delete_messages`,\n`move_messages` and deleting a folder raise a real dialog that the model cannot answer on its\nbehalf. Where it does not, they fall back to a two-call token — and say so, rather than implying\nsomebody approved. `ELICITATION=false` takes that fallback deliberately; it never removes the\nguard. See [Asking a person](https://imap-mcp.ni-c.de/guide/approval).\n\n## Requirements\n\n- Node.js 22 or newer\n- An IMAP account. Providers with two-factor authentication generally need an app-specific\n password.\n\n## Configuration\n\n| Variable | Required | Default | Description |\n| --------------------------- | -------- | ------------- | ------------------------------------------------------------ |\n| `IMAP_HOST` | yes | — | Hostname of the IMAP server, e.g. `imap.example.net` |\n| `IMAP_USER` | yes | — | Account username, usually the address |\n| `IMAP_PASSWORD` | yes | — | Password or app-specific password |\n| `IMAP_PORT` | no | `993` / `143` | Defaults by TLS mode |\n| `IMAP_TLS` | no | `implicit` | `implicit`, `starttls` or `none` |\n| `IMAP_MAILBOX` | no | `INBOX` | Mailbox the message tools default to |\n| `IMAP_READ_ONLY` | no | **`true`** | Exactly `false` registers the five mailbox tools |\n| `IMAP_ALLOW_TOOLS` | no | — | Tool names, `list_*` prefixes or `essential` |\n| `IMAP_DENY_TOOLS` | no | — | Same syntax; subtracted from the allow list |\n| `IMAP_SEEN_KEYWORD` | no | `AiSeen` | Keyword for new-mail tracking; empty turns it off |\n| `IMAP_TRUSTED_AUTHSERV_ID` | no | — | The authserv-id your provider stamps; see below |\n| `IMAP_DRAFTS_MAILBOX` | no | auto | Overrides the folder found via the `\\Drafts` flag |\n| `IMAP_MAX_MESSAGES` | no | `100` | Default page size |\n| `IMAP_MAX_ATTACHMENT_BYTES` | no | `1048576` | Ceiling for returning an attachment inline |\n| `IMAP_MAX_DOWNLOAD_BYTES` | no | `26214400` | Ceiling for writing one to disk |\n| `IMAP_MAX_EXTRACT_BYTES` | no | `10485760` | Ceiling for reading a document's text; max `67108864` |\n| `IMAP_ATTACHMENT_TYPES` | no | see below | Comma-separated content-type allowlist |\n| `IMAP_DOWNLOAD_DIR` | no | — | Setting it allows saving attachments there |\n| `IMAP_INSECURE_TLS` | no | `false` | Exactly `true` accepts a self-signed certificate |\n| `ELICITATION` | no | `true` | `false` replaces the dialog with the token. **Not prefixed** |\n\nBooleans are compared against the literal string `true`; `1`, `yes` and `True` are not true.\n`IMAP_READ_ONLY` is the mirror image: only the literal `false` turns it off, so a typo leaves\nthe write tools unregistered.\n\n> **`IMAP_ALLOW_WRITE` is gone.** It has been replaced by `IMAP_READ_ONLY`, and an installation\n> that still sets it **refuses to start**. Silently ignoring a removed security variable is the\n> worst of the options: whoever set it once believes it is still in force. The default is\n> unchanged — writes are still off unless you ask for them.\n\n### Choosing which tools load\n\n`IMAP_ALLOW_TOOLS` and `IMAP_DENY_TOOLS` take comma-separated tool names; a trailing `*`\nmatches a whole family. `essential` is a curated preset of six — `list_mailboxes`,\n`list_new_messages`, `list_messages`, `get_message`, `set_message_flags` and `move_messages`.\nFour of those are read tools, so it stays useful under the read-only default.\n\n```sh\nIMAP_ALLOW_TOOLS=essential\nIMAP_ALLOW_TOOLS=list_new_messages,get_message,move_messages\nIMAP_DENY_TOOLS=delete_messages\n```\n\nOne boundary the list cannot draw: `move_messages` copies as well as moves (`mode: \"copy\"`),\nand the two are one tool. Denying `move_messages` removes both; there is no way to keep moving\nand forbid copying, or the other way round. Both modes ask for confirmation.\n\nAn entry that matches no tool aborts startup and names it, so a typo cannot silently hide a\ntool — an absent tool is not something anyone traces back to an environment variable. A\nfiltered tool is never registered, so it is absent from `tools/list` and unknown to\n`tools/call` alike, exactly like a write tool under `IMAP_READ_ONLY`.\n\nIt covers **tools**. The attachment resources this server also exposes are not filtered.\n\nIf you run several of these servers at once, [mcp-hub](https://mcp-hub.ni-c.de) is the other\nanswer — its `/hub` endpoint replaces every server's tools with six meta-tools.\nThe password is deleted from the process environment as soon as it is read, so it is not\nvisible to child processes or in `/proc//environ`.\n\nWithout `IMAP_DOWNLOAD_DIR` this server never writes to the filesystem. The three size limits are\nseparate on purpose, because they answer three different questions:\n`IMAP_MAX_ATTACHMENT_BYTES` protects the model's context window,\n`IMAP_MAX_DOWNLOAD_BYTES` protects your disk, and `IMAP_MAX_EXTRACT_BYTES` bounds how much\nhostile input one parser is handed. Raising any one of them is not a request to raise the others.\n\nThe server starts without credentials on purpose — it completes the handshake and lists its\ntools, and every call then fails with setup instructions instead of reaching a server.\n\n## Installation\n\n### Claude Code\n\n```sh\nclaude mcp add imap-mcp \\\n -e IMAP_HOST=imap.example.net -e IMAP_USER=you@example.net -e IMAP_PASSWORD=… \\\n -- npx -y @ni-c/imap-mcp\n```\n\n### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"imap-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ni-c/imap-mcp\"],\n \"env\": {\n \"IMAP_HOST\": \"imap.example.net\",\n \"IMAP_USER\": \"you@example.net\",\n \"IMAP_PASSWORD\": \"…\"\n }\n }\n }\n}\n```\n\n### Codex\n\n```toml\n[mcp_servers.imap-mcp]\ncommand = \"npx\"\nargs = [\"-y\", \"@ni-c/imap-mcp\"]\nenv = { IMAP_HOST = \"imap.example.net\", IMAP_USER = \"you@example.net\", IMAP_PASSWORD = \"…\" }\n```\n\n### Docker\n\n```sh\ndocker run --rm -i \\\n -e IMAP_HOST=imap.example.net \\\n -e IMAP_USER=you@example.net \\\n -e IMAP_PASSWORD=… \\\n ghcr.io/ni-c/imap-mcp\n```\n\nSaving attachments needs a writable directory, and the image runs as uid 1000 — so a\nbind mount has to be owned by it on the host: `-e IMAP_DOWNLOAD_DIR=/data -v\n\"$PWD/attachments:/data\"` with `chown 1000:1000 attachments`. Without\n`IMAP_DOWNLOAD_DIR` the container never writes anything.\n\n### Through mcp-hub\n\nA client that cannot spawn a local process — ChatGPT connectors, Claude on the web,\nCursor, LibreChat — reaches imap-mcp through [mcp-hub](https://mcp-hub.ni-c.de): one\ncontainer serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login\nbehind a single password and long-lived tokens for the clients that cannot do OAuth. Its\n`/hub` endpoint puts every server behind six meta-tools, so one connector reaches all of\nthem without N×tool schemas in the model's context, and it speaks both protocol revisions\n— a question this server asks travels through it to the person at the far end.\n\nIts `/config/mcp.json` uses Claude Code's format, so the entry is the one you already\nhave:\n\n```json\n{\n \"mcpServers\": {\n \"imap-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ni-c/imap-mcp\"],\n \"env\": {\n \"IMAP_HOST\": \"imap.example.net\",\n \"IMAP_USER\": \"me@example.net\",\n \"IMAP_PASSWORD\": \"…\",\n \"IMAP_ALLOW_TOOLS\": \"essential\"\n },\n \"denyTools\": [\"delete_messages\"]\n }\n }\n}\n```\n\n`allowTools` and `denyTools` there are the hub's **own** per-server filter, which is not\nthe same thing as `*_ALLOW_TOOLS` in `env` — the difference, and the mistake it invites,\nare in the [client guide](https://imap-mcp.ni-c.de/guide/clients#through-mcp-hub).\n\n## Tools\n\n**Read** — always registered\n\n| Tool | What it does |\n| ------------------- | ---------------------------------------------------------------------------------------- |\n| `get_server_info` | Capabilities, permanent flags, whether the keyword is storable, which tool groups are on |\n| `list_mailboxes` | Every folder with message and unseen counts and its special-use role |\n| `list_messages` | Lists and searches: sender, recipient, subject, body, date range, flags |\n| `list_new_messages` | Messages not handed over yet; marks them afterwards, `dry_run` to preview |\n| `get_message` | Headers and body, fenced untrusted, plus the security assessment; `include_thread` |\n| `get_attachments` | Without `part_id` lists them, with `part_id` reads, extracts or saves one |\n\n**Mailbox** — needs `IMAP_READ_ONLY=false`\n\n| Tool | Confirmation |\n| ------------------- | --------------------------------------------------------- |\n| `set_message_flags` | none — flags are reversible, and `\\Deleted` is refused |\n| `move_messages` | 👤 for both `move` and `copy`, 🔒 where the client cannot |\n| `delete_messages` | 👤 asks the user, 🔒 where the client cannot |\n| `manage_mailbox` | 👤 for `delete`, 🔒 for `rename`, none for `create` |\n| `save_draft` | none — a draft does not leave the mailbox |\n\n👤 raises a dialog the model cannot answer · 🔒 needs a confirmation token: call once to\nreceive one, then again with it.\n\n`copy` is confirmed as well as `move`, because the thing that cannot be taken back is not\nthe deletion — it is the disclosure. A destination is a free-form folder name, and on a\nshared account or a public namespace one call hands every message to everyone who can read\nit, leaving the source folder untouched. For the same reason `set_message_flags` refuses to\nadd `\\Deleted`: it is half a deletion, and the next client to close the mailbox may finish\nit. Use `delete_messages`, which asks.\n\nNeither a confirmation nor a dialog quotes a mailbox name inside its own sentence — folder\nnames come from the account, which on a shared mailbox means a colleague chose them.\n\n### Structured output\n\nEvery tool declares an `outputSchema` and answers with `structuredContent`\nalongside the text block, so a client can use the result without parsing prose:\n\n```jsonc\n{\n \"untrusted\": true,\n \"source\": \"imap\",\n \"mailbox\": \"INBOX\",\n \"total_matching\": 214,\n \"offset\": 0,\n \"returned\": 25,\n \"next_offset\": 25,\n \"messages\": [{ \"uid\": 4711, \"subject\": \"…\", \"from\": \"…\", \"seen\": false }],\n}\n```\n\nEvery tool that reports anything out of the mailbox carries `untrusted: true`\nand `source: \"imap\"` as fields — a sender display name, a folder name a\ncolleague chose and an attachment filename are all attacker-controllable, and\nthey reach the model through the listing tools long before anyone opens a\nmessage. Only `get_server_info` and the five write tools are without it: those\nreport this server's own configuration, or what it just did with the uids it was\ngiven.\n\n`get_message` and a text attachment keep the per-call nonce fence in the text\nblock — the structured half states the same fields, so a client is not made to\nparse the fence to find them. An image attachment keeps its bytes in the content\nblock, where a client renders them, rather than repeating the base64.\n\nA refusal is now an **error result**: an attachment the policy rejects, one whose\nbytes are an executable whatever it claimed, one too large to inline. Each was a\nplain result that read like an answer.\n\nAttachments are also available as MCP resources at `imap://message/{uid}/part/{partId}`, which\nmatters where the server has no useful filesystem. The resource path runs the same allowlist,\nsize limit and magic-byte check as the tool — it is not a second, unguarded door.\n\n## Not exposed, on purpose\n\nNo sending, no SMTP, no raw IMAP passthrough, no `APPEND` of arbitrary MIME, no HTML\ncomposition, no OAuth2, and **no OCR** — a scanned PDF has no text to extract and says so\nrather than guessing. The first is the whole security argument (see `SECURITY.md`); the\nsecond would make every guard here optional; the last is planned but needs a test account\nbefore it ships.\n\nAnd one thing the tool filter does not cover: **attachment resources**. `IMAP_ALLOW_TOOLS`\nnarrows `tools/list`, not `resources/list`, so a server with a narrow allow list still serves\nthose. `IMAP_DOWNLOAD_DIR` and the content-type allowlist are what constrain them — worth\nknowing before concluding that a filtered install reaches less of the mailbox than it does.\n\n## Safety\n\n- **Every result carrying mailbox content is marked untrusted**, message bodies additionally\n fenced with a per-call nonce and marked line by line.\n- **Attachments pass two independent gates.** The declaration is checked against a\n content-type allowlist, an executable-extension refusal list and a size ceiling; the bytes\n are then checked against magic numbers. An executable renamed to `.pdf` and declared\n `application/pdf` clears every declaration check and fails on its bytes — including when\n saving to disk, where it would be more dangerous, not less.\n- **A `part_id` must come from a listing call**, so the body cannot be pulled out through the\n attachment tool and escape its framing.\n- **Documents are parsed in a process that can be killed.** `mode: \"text\"` reads a PDF or\n Office file with a bundled PDF.js and a ZIP reader — the only place this server parses a\n binary a stranger sent. It runs in a child process with a heap limit and a timeout, its\n stdout discarded rather than shared with the JSON-RPC transport, PDF.js's `eval` support\n off, compressed streams measured against a ceiling _before_ PDF.js inflates them, and an\n entry allowlist that decides what is decompressed _before_ the buffer is sized. Nothing in\n that path touches the network or the filesystem.\n- **Extracted text says what it is.** Extraction returns every text-drawing instruction in a\n file, including text set below one point or drawn in the colour of the paper, and returns\n nothing that was drawn as a picture. The result says so above the fence, because \"the\n document says X\" is otherwise a claim the user has no way to check.\n- **Downloads cannot escape their directory.** The target comes only from the environment, the\n filename is sanitised, the resolved path is re-checked, and the file is opened with `wx` and\n mode `0600` — so nothing is overwritten and no planted symlink is followed.\n- **Mailbox names, flags and addresses are refused if they contain line breaks.** IMAP is a\n line protocol and a draft is a mail header; a CR is an injection primitive, not a typo.\n- **TLS is never disabled globally.** `IMAP_INSECURE_TLS` is scoped to the connection it names;\n `NODE_TLS_REJECT_UNAUTHORIZED` appears nowhere.\n- **Every change to the mailbox is logged to stderr** with the UIDs and folder — never the\n subject. stderr is the one channel the model does not read.\n- **Responses are bounded.** Whole items are dropped rather than the JSON being sliced, and the\n truncation notice comes first so the recovery hint survives.\n\n`SECURITY.md` has the trust model, what these measures do _not_ cover, and how to report a\nvulnerability.\n\n## Documentation\n\nThe full guide, tool reference and security notes live at\n**[imap-mcp.ni-c.de](https://imap-mcp.ni-c.de)** (source in [`docs/`](docs/)).\n\n## Development\n\n```bash\nnpm install\nnpm test\nnpm run build\n```\n\nThe test suite runs against an in-memory IMAP fake, so it needs no server and no\nnetwork. For a live server to point the real thing at, see\n[CONTRIBUTING.md](CONTRIBUTING.md) — it starts a throwaway mailbox in a container.\n\n## Releasing\n\n1. Add the CHANGELOG entry and bump `package.json`.\n2. `npm run lint && npm run build && npm run test:coverage`\n3. Commit, then push a signed tag: `git tag -s vX.Y.Z -m \"vX.Y.Z\" && git push origin main vX.Y.Z`\n\nThe release workflow publishes to npm (Trusted Publishing, with provenance), creates\nthe GitHub release from the CHANGELOG section and updates the MCP Registry entry.\n\n## Contributing\n\nIssues, discussions and pull requests are welcome — see\n[CONTRIBUTING.md](CONTRIBUTING.md). For vulnerabilities please use\n[private reporting](https://github.com/ni-c/imap-mcp/security/advisories/new)\nrather than a public issue; the policy is in [SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE) © Willi Thiel\n",
"bytes": 23821,
"sha": "24dbbac7422b3b76788d34b5aa7a6c96a0a253db54bd3b8db0ad21f2c44aaa6a",
"repo_slug": "ni-c/imap-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_ni_c_imap_mcp_8ba18b32/readme"
}