imap-mcp

imap-mcpYour mailbox as tools, without a way to send

Find the mail, read it, file it — every message fenced as untrusted content, and the write tools off unless you turn them on

Get started
Tools reference
GitHub

  • Mail is evidence, not instruction

    Anyone in the world can send you mail, so every body arrives fenced between BEGIN/END UNTRUSTED EMAIL CONTENT markers carrying a random nonce, with that nonce repeated on every line inside. Text outside those markers is the only text this server wrote.

  • It knows what is new

    list_new_messages tracks what the assistant has already seen with its own IMAP keyword, so "anything new?" has an answer that does not depend on whether you have read the mail yourself — and reading it here does not mark it read in your client.

  • Only the tools you want

    IMAP_READ_ONLY=true registers the read tools and nothing else. IMAP_ALLOW_TOOLS cuts finer — essential for a curated handful, your own comma-separated list, or a whole family with list_* — and IMAP_DENY_TOOLS subtracts. Whatever is filtered out does not exist on the protocol rather than failing when called, and a name that matches no tool stops the server at startup instead of quietly going missing.

  • Safe by default

    Deleting messages, moving or copying them and deleting a folder ask a person first, through MCP elicitation — a dialog the model cannot answer on its behalf, falling back to a server-issued token where the client cannot show one. Upstream content is marked untrusted, and read-only mode simply does not register the write tools.

How imap-mcp sits between an MCP client and a mailboxAn MCP client speaks stdio to imap-mcp, which connects to an IMAP server over TLS; message bodies come back fenced as untrusted content.MCP clientClaude, Codex, …imap-mcp11 toolsasks a personIMAPany IMAP mailboxstdioIMAPTLSThis server never sends mail.
The server holds no state of its own beyond short-lived approvals; what the assistant has seen lives in the mailbox, as a keyword.

What it looks like ​

A terminal session: listing the tools registered under the read-only default, listing an inbox, then reading a phishing message — which comes back with the injection shapes named before anything else, the body fenced line by line with a per-call nonce, and the tracking beacon defused

Four calls against a throwaway mailbox. The last two are the point: the message asks the assistant to forward the inbox to a stranger and carries a tracking pixel, and both arrive labelled as what they are rather than acted upon. The recording is reproducible — docs/demo.tape and docs/demo-seed.mjs build the mailbox from scratch, and nothing in it comes from a real account.

Running it elsewhere ​

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — cannot start imap-mcp the way Claude Code does. mcp-hub is the bridge: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end instead of ending at the gateway.

Its configuration is Claude Code's mcpServers format, so the entry you already have is the entry it takes: Through mcp-hub.

Released under the MIT License.

Copyright © 2026 Willi Thiel