Your Mail MCP server

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:

and summarize who promised what."

• "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,

• "What arrived this morning, across all my accounts, that actually needs me?"

Use it for:

history, every account in one index, phrased the way you think.

• Search that understands questions. Full-text search over your whole

with junk already filtered out, from wherever you are.

• Triage from your phone. A morning summary of what came in overnight,

the thread and into your coding or writing session.

• Mail as context for other work. Pull the client's requirements out of

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.

• Agents you can leave running. The process has no path that sends,

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.

mkdir your-mail && cd your-mail
curl -fsSLO https://raw.githubusercontent.com/wildsurfer/your-mail-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/wildsurfer/your-mail-mcp/main/accounts.example.json -o accounts.json

Put your accounts in accounts.json. ${WORK_PASS} is replaced from the environment, so the file itself holds no password:

{
  "accounts": [
    { "name": "work", "host": "imap.gmail.com", "user": "you@example.com", "password": "${WORK_PASS}" },
    { "name": "personal", "host": "imap.mail.me.com", "user": "you", "password": "${PERSONAL_PASS}" }
  ]
}

Put the passwords in .env next to compose.yaml:

# .env
WORK_PASS=your-gmail-app-password
PERSONAL_PASS=your-icloud-app-specific-password

Shortened. The full README is on GitHub.