your-mail-mcp

your-mail-mcp is a self-hosted, open-source MCP (Model Context Protocol) server built in Go by Ivan Kuznetsov (wildsurfer). It mirrors one or more IMAP accounts into a local maildir using mbsync, indexes them with notmuch, and exposes eleven read-only tools to any MCP-compatible AI client — including Claude, Claude Code, and Codex — over authenticated HTTP with OAuth. The project is licensed under the MIT License and published on GitHub.

What It Is

your-mail-mcp sits between your email accounts and your AI assistant, letting you ask natural-language questions about your mail history without giving the AI write access to anything. It is a pure read path: the architecture enforces this at every layer, from the mbsync configuration (Sync Pull, Create Near, Remove None, Expunge None) to the Go code, which issues only IMAP LIST commands and never selects a mailbox or fetches a message directly. There is no send, delete, move, or tag operation anywhere in the server.

How the Read-Only Architecture Works

The server's eleven tools cover the full read surface of a mail index:

• search — full-text search returning thread summaries as JSON, using notmuch query syntax (from:, to:, subject:, tag:, date: ranges, combined with and/or/not)
• show / thread / text — retrieve a single message, a full thread, or the plain-text body of one message
• attachment — serve one MIME part read-only: images inline up to 5 MB, text as a marked block, binaries as a short-lived signed download link
• ids / files / count — return message IDs, maildir paths, or a count matching a query
• folders / status / refresh — inspect account sync health, trigger an INBOX sync, and list folders with last-sync timestamps

Because there is no write path, the README notes that scheduled digests and always-on agents are safe to run: a malicious email that reaches the assistant gets read and nothing more.

Deployment Model

The server ships as a container image (ghcr.io/wildsurfer/your-mail-mcp) for amd64 and arm64, built by CI. Setup is two files — compose.yaml and accounts.json — plus docker compose up -d. Three deployment cases are documented:

1. Local only — binds to loopback, no TLS needed, works with Claude Code and Codex CLI
2. Public via tunnel — Tailscale Funnel or Cloudflare Tunnel gives the local server an HTTPS address reachable from a smartphone or Claude's web/desktop connectors
3. VPS — same setup on a rented server, keeping the mail mirror online independently of a personal machine

Release binaries for Linux and macOS (amd64 and arm64) are also published on the releases page for use without Docker, requiring mbsync, notmuch, and w3m on PATH. Windows is not supported due to maildir filesystem semantics and the absence of mbsync.

MCP Client Integration

The server speaks streamable HTTP MCP with OAuth and supports dynamic client registration, so clients like Claude (web, desktop, and mobile via connector sync) and ChatGPT (with developer mode enabled) require no manual OAuth credential pasting. Claude Code uses claude mcp add --transport http, and Codex uses codex mcp add. For clients with broken OAuth support, mcp-remote can bridge the OAuth dance over stdio.

Update: v0.2.0

The latest release is v0.2.0, published on 2026-08-26. The repository was created on 2026-08-20 and last pushed on 2026-08-26, indicating active early development. The project is registered in the MCP registry (io.github.wildsurfer/your-mail-mcp) and has a Glama score badge, signaling integration with the broader MCP server ecosystem.