Your Mail MCP

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.

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

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. If you would rather they did not, give an account pass_cmd instead of password: a command that prints the secret, such as cat /run/secrets/work_pass for a Docker secret, or security find-generic-password -s your-mail -a work -w on a Mac. mbsync runs it at connect time and nothing on disk or in the environment holds the password. See the reference.

docker compose up -d

docker compose logs -f # watch the first sync

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:

claude mcp add your-mail -- docker exec -i your-mail-mcp your-mail-mcp stdio

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:

{ "command": "docker", "args": ["exec", "-i", "your-mail-mcp", "your-mail-mcp", "stdio"] }

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:

/plugin marketplace add wildsurfer/your-mail-mcp

/plugin install your-mail@your-mail-mcp

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 anything you want kept fresh.

Use it from your phone

The Claude and ChatGPT smartphone apps reach a connector through the vendor's servers, so the server needs a public HTTPS address. A tunnel gives it one: the tunnel dials out, nothing listens on your home network, and the mail stays on your machine.

With Tailscale installed, one command, the same on macOS and Linux:

tailscale funnel --bg 8080

It prints a hostname like https://your-machine.your-tailnet.ts.net, and --bg keeps it running across reboots. Put that hostname in .env together with a passphrase, then restart:

# .env

PUBLIC_URL=https://your-machine.your-tailnet.ts.net OAUTH_PASSPHRASE=pick-a-long-one-you-can-type-on-a-smartphone

docker compose up -d

OAUTH_PASSPHRASE is the only credential between the internet and your mail. A wrong guess costs one second and guesses are serialised, and neither of those saves a short passphrase. Use a long one you can still type on a phone.

Funnel needs HTTPS certificates and the Funnel node attribute enabled for your tailnet; the CLI offers to add the policy line the first time. tailscale funnel status shows what is exposed, and tailscale funnel --https=443 off takes it down.

Now add the connector. Neither the Claude nor the ChatGPT smartphone app can add one, so you do it once on the web, and it then appears on the phone.

1. On claude.ai or in Claude Desktop, open Settings → Connectors and add a custom connector.
2. Give it a name and the URL /mcp. Leave the advanced OAuth fields empty; the server registers clients itself.
3. Claude opens the consent page. Enter your OAUTH_PASSPHRASE.
4. Open the Claude app on your phone. The connector is already there; turn it on for a conversation from the tools menu in the composer.

PUBLIC_URL has to match what you type into the client exactly. The server publishes PUBLIC_URL + /mcp as the resource in its OAuth metadata, and a mismatch there is the most common reason a connector refuses to add.

Cloudflare Tunnel instead of Tailscale, on your own domain

Use this for a hostname on a domain you own. mail.example.com below has to be your domain, already added to your Cloudflare account; Cloudflare does not hand out hostnames for named tunnels.

cloudflared tunnel login

cloudflared tunnel create your-mail

create prints the tunnel's UUID and the path of the credentials file it wrote; cloudflared tunnel list prints the UUID again if you lose it. Route the hostname, then write ~/.cloudflared/config.yml:

cloudflared tunnel route dns your-mail mail.example.com

tunnel: your-mail

credentials-file: /Users/you/.cloudflared/f9e2….json # the path create printed url: http://localhost:8080

cloudflared tunnel run your-mail

To keep it running: on Linux, sudo cloudflared service install. On macOS, install it through Homebrew and use brew services start cloudflared, because the sudo install path looks for its certificate under the root user's home and will not find the one cloudflared tunnel login wrote to yours.

Then set PUBLIC_URL=https://mail.example.com in .env and docker compose up -d.

ChatGPT, and Claude Code or Codex from another machine

ChatGPT. Custom MCP connectors live behind developer mode, which needs a Pro, Plus, Business, Enterprise or Education account and is only available on the web.

1. In ChatGPT on the web, open Settings → Security and login and turn on Developer mode. On Business and Enterprise workspaces an admin may have to allow it first.
2. Add a connector for a remote MCP server with the URL /mcp and OAuth as the authentication. ChatGPT supports dynamic client registration, so there is nothing to paste.
3. Approve the consent page with your OAUTH_PASSPHRASE.
4. Open ChatGPT on your phone and enable the connector in a chat.

These menus move. If the names above do not match what you see, look for developer mode in settings, then for the place that adds a connector by URL. ChatGPT disables some MCP write actions on mobile, which changes nothing here because this server has none.

Claude Code:

claude mcp add --transport http your-mail https://your-host/mcp

Codex:

codex mcp add your-mail --url https://your-host/mcp

codex mcp login your-mail

Run it on a server

Pick this when the mirror should stay up whether or not your machine is on. It costs a few dollars a month and one real trade-off: a full plaintext copy of your mail moves onto a rented disk, with the app passwords next to it. The install is the quick start plus a tunnel, on someone else's computer, and the box needs hardening before it holds your mail. Both are in docs/server.md.

The tools

Eleven tools, all read-only:

| Tool | What it d