imap-mcp

# imap-mcp

<!-- badges: start -->

[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/imap-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/imap-mcp/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ni-c/imap-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/ni-c/imap-mcp)
<a href="https://socket.dev/npm/package/@ni-c/imap-mcp"><img src="https://socket.dev/api/badge/npm/package/@ni-c/imap-mcp" alt="Socket supply-chain report" height="20"></a>
[![Glama score](https://glama.ai/mcp/servers/ni-c/imap-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/imap-mcp)
<br>
[![npm version](https://img.shields.io/npm/v/%40ni-c%2Fimap-mcp)](https://www.npmjs.com/package/@ni-c/imap-mcp)
[![container image](https://img.shields.io/badge/ghcr.io-ni--c%2Fimap--mcp-4f46e5?logo=docker&logoColor=white)](https://github.com/ni-c/imap-mcp/pkgs/container/imap-mcp)
[![HTTP via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-4f46e5?logo=modelcontextprotocol&logoColor=white)](https://mcp-hub.ni-c.de)
<br>
[![docs](https://img.shields.io/badge/docs-imap--mcp.ni--c.de-4f46e5?logo=readthedocs&logoColor=white)](https://imap-mcp.ni-c.de)
[![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
<!-- badges: end -->

A [Model Context Protocol](https://modelcontextprotocol.io) (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](#choosing-which-tools-load).

<!-- <picture> is resolved against the colour scheme of the page showing it, so GitHub
     picks the variant that matches its own theme toggle. npm strips <picture> and
     <source> when it sanitises the README and keeps the <img>, which is why that
     fallback carries its own dark card. The URLs are absolute because relative ones
     are simply invisible on the npm package page. -->
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://imap-mcp.ni-c.de/architecture-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://imap-mcp.ni-c.de/architecture-light.svg">
  <img src="https://imap-mcp.ni-c.de/architecture.svg" alt="An MCP client talking to imap-mcp over stdio, which connects to an IMAP server over TLS and returns message bodies fenced as untrusted content" width="800">
</picture>

<img src="https://imap-mcp.ni-c.de/demo.gif" alt="Listing the tools registered under the read-only default, listing an inbox, and reading a phishing message — which comes back with the injection shapes named first, the body fenced line by line, and the tracking beacon defused" width="800">

## 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](https://msrc.microsoft.com/update-guide/vulnerability/CVE-2025-32711), 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.

That covers folder names too, and it did not always: a folder name is chosen by whoever created
the folder, which on a shared mailbox is not necessarily you. `list_mailboxes` returns the name
twice — `path` exactly as the server spelled it, because that is the handle every other tool
takes, and `display_name` cleaned up for reading, with a warning on the entry when the two differ.

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 and moving ask a person.** Where the client supports MCP elicitation, `delete_messages`,
`move_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. `ELICITATION=false` takes that fallback deliberately; it never removes the
guard. See [Asking a person](https://imap-mcp.ni-c.de/guide/approval).

## Requirements

- Node.js 22 or newer
- An IMAP account. Providers with two-factor authentication generally need an app-specific
  password.

## Configuration

| Variable                    | Required | Default       | Description                                                  |
| --------------------------- | -------- | ------------- | ------------------------------------------------------------ |
| `IMAP_HOST`                 | yes      | —             | Hostname of the IMAP server, e.g. `imap.example.net`         |
| `IMAP_USER`                 | yes      | —             | Account username, usually the address                        |
| `IMAP_PASSWORD`             | yes      | —             | Password or app-specific password                            |
| `IMAP_PORT`                 | no       | `993` / `143` | Defaults by TLS mode                                         |
| `IMAP_TLS`                  | no       | `implicit`    | `implicit`, `starttls` or `none`                             |
| `IMAP_MAILBOX`              | no       | `INBOX`       | Mailbox the message tools default to                         |
| `IMAP_READ_ONLY`            | no       | **`true`**    | Exactly `false` registers the five mailbox tools             |
| `IMAP_ALLOW_TOOLS`          | no       | —             | Tool names, `list_*` prefixes or `essential`                 |
| `IMAP_DENY_TOOLS`           | no       | —             | Same syntax; subtracted from the allow list                  |
| `IMAP_SEEN_KEYWORD`         | no       | `AiSeen`      | Keyword for new-mail tracking; empty turns it off            |
| `IMAP_TRUSTED_AUTHSERV_ID`  | no       | —             | The authserv-id your provider stamps; see below              |
| `IMAP_DRAFTS_MAILBOX`       | no       | auto          | Overrides the folder found via the `\Drafts` flag            |
| `IMAP_MAX_MESSAGES`         | no       | `100`         | Default page size                                            |
| `IMAP_MAX_ATTACHMENT_BYTES` | no       | `1048576`     | Ceiling for returning an attachment inline                   |
| `IMAP_MAX_DOWNLOAD_BYTES`   | no       | `26214400`    | Ceiling for writing one to disk                              |
| `IMAP_MAX_EXTRACT_BYTES`    | no       | `10485760`    | Ceiling for reading a document's text; max `67108864`        |
| `IMAP_ATTACHMENT_TYPES`     | no       | see below     | Comma-separated content-type allowlist                       |
| `IMAP_DOWNLOAD_DIR`         | no       | —             | Setting it allows saving attachments there                   |
| `IMAP_INSECURE_TLS`         | no       | `false`       | Exactly `true` accepts a self-signed certificate             |
| `ELICITATION`               | no       | `true`