your-mail-mcp: Instructions file for Claude Code

your-mail-mcp

A self-hosted MCP server that gives an MCP client read access to one or more IMAP accounts. Mail is mirrored to a local maildir by mbsync, indexed by notmuch, and served over streamable HTTP behind an in-process OAuth 2.0 authorization server.

This file is the briefing for anyone changing the code. README.md is for operators running it. The reasoning behind the design is in docs/specs/2026-08-19-your-mail-mcp-design.md, and what was verified against real tools is in docs/reviews/.

Status

v1 is implemented: eleven read tools, multi-account sync, SPECIAL-USE junk discovery, OAuth with dynamic client registration, and a container image.

Running against one real iCloud account and two real Gmail accounts. That is one operator's mailbox, so see "Before trusting it" below for what is still unproven.

Invariants

These are the reasons this project exists in this shape. Do not weaken one without changing the spec first.

• Nothing in the process may write to a mail account. mbsync is configured Sync Pull / Create Near / Remove None, with Expunge None by default and Expunge Near — which deletes local files only — for an account that opts into expunge_local. The file is generated by the program rather than mounted, so the directives cannot be edited into something that pushes. There is no send, delete, move or tag path against any account. The one local deletion in Go code is the account's own -recent bootstrap store, removed once the full mirror covers it.
• The only IMAP operation in Go code is LIST, used once per account to find the junk and trash folders. It never selects a mailbox and never fetches a message, and the client object does not escape the function that opens it.
• Every byte of mail text reaching the model passes through render(). page() in mcp.go is the only place that constructs text content, and render neutralises the marker sentinel so mail cannot forge the untrusted-content wrapper. The one deliberate exception is image attachment parts: text cannot mark pixels, so the attachment tool returns images as typed MCP content whose schema names them attacker-authored, capped at 5MB. Textual parts — text/*, JSON, XML, message/rfc822 — pass through render; every other binary is served only as a short-lived signed link to GET /attachment/{id}/{part} (or, with no listener, a file under the index for docker cp) (bearer token also accepted): those bytes go to a shell or a browser, never into model context, so no cap and no render apply there.
• Junk and trash are excluded from search by default, discovered per account through RFC 6154 SPECIAL-USE so it works whatever the folders are named and in whatever language.
• Exactly two dependencies: modelcontextprotocol/go-sdk and emersion/go-imap/v2. Everything else is the standard library, tests included.