wildsurfer/your-mail-mcp

Your mail already holds the answers: booking references, gate codes,
invoices, warranty periods, promises people made in writing. This server lets
your AI assistant find them, and it can only read.
**Ask it things like:**
- "Find the booking reference for the June ferry."
- "What was the wifi password the hotel sent last summer?"
- "What did the accountant answer about VAT, and when?"
- "Collect everything between me and the builder about the roof, in order,
and summarize who promised what."
- "What arrived this morning, across all my accounts, that actually needs me?"
**Use it for:**
- **Search that understands questions.** Full-text search over your whole
history, every account in one index, phrased the way you think.
- **Triage from your phone.** A morning summary of what came in overnight,
with junk already filtered out, from wherever you are.
- **Mail as context for other work.** Pull the client's requirements out of
the thread and into your coding or writing session.
- **Agents you can leave running.** The process has no path that sends,
deletes or moves a message. A malicious email that reaches your assistant
gets read, and that is all that can happen to it. Scheduled digests and
always-on agents are a calm thing to run.
Setup is two files and docker compose up -d. See Quick start.
How it works
A self-hosted MCP server. It mirrors one or more IMAP accounts into a local
maildir with mbsync, indexes them with
notmuch, and answers tool calls from that index.
The Claude and ChatGPT apps attach over HTTPS with OAuth; Claude Code, Codex,
Cursor and Claude Desktop attach over stdio on the same machine. Any MCP
client works, so if you want full privacy you can attach one backed by a
local LLM and your mail never leaves your machine.
Mail only ever moves left to right in that picture. The mirror is pull-only
by configuration. The one connection the Go code makes toward a provider is
an IMAP LIST per account, to learn what that server calls its junk and
trash folders; it never selects a mailbox and never fetches a message.
Security has the full list of what the process cannot do. The
diagram source is
docs/diagrams/how-it-works.html.
Quick start
On your machine, for your machine. Docker is the only requirement; the image
at ghcr.io/wildsurfer/your-mail-mcp is built by CI for amd64 and arm64.
Put your accounts in accounts.json. ${WORK_PASS} is replaced from the
environment, so the file itself holds no password:
Put the passwords in .env next to compose.yaml:
compose.yaml passes WORK_PASS and PERSONAL_PASS into the container. An
account with another variable name needs that name added under
environment: there as well.
Two provider details cost people the most time. Gmail accepts only an app
password over IMAP, and app passwords need 2-step verification turned on
first. iCloud wants the short name before @icloud.com as user; the full
address fails to log in. Every key of the file is in
the reference.
These two files hold your mail passwords. Keep the directory out of version
control and out of backups that leave the machine.
Today's INBOX mail is searchable within minutes. The full history follows at
whatever pace the provider allows, and the status tool reports how far it
has got. A large Gmail account takes days, because Google caps IMAP downloads
at about 2.5GB per day; set SYNC_TIMEOUT=8h in .env for that first
mirror. Provider notes has the details.
Then connect a client. Claude Code:
Cursor and VS Code add it in one click, once the stack is up:
Claude Desktop, Cursor, Codex and other stdio clients
Any client that starts an MCP server as a command:
Each session is a bridge into the running container, so every client sees
the same index and the same sync. Close the client and the session goes with
it.
Claude Code can also take it as a plugin, which adds the server and an
email skill that knows the query syntax:
Without a running stack,
docker run -i --rm --env-file .env -v index:/index -v mail:/mail -v ./accounts.json:/config/accounts.json:ro ghcr.io/wildsurfer/your-mail-mcp
starts a daemon for the life of one session. Fine for a look; use compose for