mailindex-mcp

mailindex-mcp

A mail client for an AI agent. Everything you can do in Thunderbird — search, move, mark, delete, draft — over your own index, on your own machine.

Most email MCP servers forward each question straight to IMAP. That answers "show me my last 10 messages" and falls apart on everything else: SEARCH is inconsistent between providers, it cannot see inside attachments, it never tells the model whether it actually searched everything, and it cannot do a thing about what it finds.

So when you ask an assistant to clear eight thousand newsletters out of your inbox, it tells you that would be eight thousand tool calls and suggests you go and do it by hand in the web interface.

This one keeps its own copy of your mail and acts on it:

delete_mail(account_id=3, participants=["newsletter@example.com", ...])

→ matched: 4147, affected: 4147, to: "[Google Mail]/Bin"

One call. One connection. Six seconds. That is the difference between a search box and a mail client.

A real question against a live index of about 59,000 messages across six accounts. One string is blurred: a case number belonging to a real filing.

Why this instead of the other email MCP servers

What it costs you, stated up front. You run PostgreSQL and a container. The index is about 28 MB per 1,000 messages — a 50,000-message archive is roughly 1.5 GB — and the image is 1.25 GB because it carries OCR language data. The first sync downloads every message once; search works on what has arrived while the rest continues in the background, and each account reports its own coverage so the model knows what it has not seen yet.

In exchange your assistant can answer questions about mail from years ago, including text inside attachments, and then act on the answer. None of it leaves your machine.

Quickstart

Five minutes, local only, no accounts to create anywhere.

git clone https://github.com/alexanderkrauck/mailindex-mcp.git

cd mailindex-mcp cp .env.example .env docker compose up -d

Every compose file here pulls ghcr.io/alexanderkrauck/mailindex-mcp — amd64 and arm64, so a Raspberry Pi or an Apple Silicon machine works the same way. Append --build to any of them to compile it yourself instead; expect several minutes, because the image carries OCR language data.

Pin a version for anything you care about. This is pre-1.0: the schema changes between releases and migrations run automatically on start, so an unpinned latest can migrate your database the moment you restart.

MAILINDEX_IMAGE=ghcr.io/alexanderkrauck/mailindex-mcp:0.1.0 docker compose up -d

MAILINDEX_IMAGE works with all three compose files, and belongs in your .env rather than on the command line. Note the image tag has no v — the git tag is v0.1.0, the image is 0.1.0, and 0.1 follows the latest patch of that minor version.

Check it came up:

curl http://localhost:8002/api/v1/health

The default development mode is unauthenticated and Docker binds it to 127.0.0.1 only. It is meant for exactly this: trying the thing out on your own machine.

Connect your AI client

Do this before connecting a mailbox — it is how you connect one.

claude mcp add --transport http mail http://localhost:8002/mcp

For other clients, point them at http://localhost:8002/mcp over streamable HTTP. Then ask something your inbox search would struggle with — a phrase inside a PDF someone sent you three years ago works well.

Connect a mailbox

Just ask your client — add_mail_account is one of the tools:

Connect my mailbox you@example.com, IMAP imap.example.com, SMTP

smtp.example.com

Do not give it the password. Asked without one, it hands you back a short-lived URL to a form that asks for the password alone and sends it from your browser straight to the server. It never passes through the model, never lands in the conversation transcript your AI provider keeps, and it is the only way that works with clients such as ChatGPT that refuse to transmit secrets.

Use an app password from your provider's security settings, never your account login password. For Gmail, ask it to start the Gmail OAuth flow instead: that uses the Gmail API and survives label changes better. Microsoft 365 and Exchange Online accept no password at all, so ask it to connect a Microsoft mailbox: you sign in at Microsoft and approve what the server may do, exactly as with Gmail (setup).

Or over HTTP, if you prefer a shell

curl -X POST http://localhost:8002/api/v1/accounts \

-H 'Content-Type: application/json' \ -d '{ "name": "personal", "account_name": "you@example.com", "username": "you@example.com", "password": "your-app-password", "host": "imap.example.com", "port": 993, "smtp_host": "smtp.example.com", "smtp_port": 465 }'

Synchronization starts on its own and runs in the background. Search works on what has arrived already — ask "how much of my mail have you indexed so far?" and it will tell you exactly, per account, because every search reports its own coverage rather than pretending to be complete.

Which setup do I need?

Four ways people arrive at this, and the shortest honest path for each.

"I want to see if this is real" — 5 minutes, your laptop

Everything runs locally, nothing to sign up for.

git clone https://github.com/alexanderkrauck/mailindex-mcp.git

cd mailindex-mcp && cp .env.example .env docker compose up -d # pulls the published image claude mcp add --transport http mail http://localhost:8002/mcp

Add a mailbox with an app password (see below), wait for it to sync, then ask your client something your inbox search would lose. What you need: Docker, and an app password from your provider. What to expect: the first build compiles psycopg2 and pulls ~130 MB of OCR language data, so it takes minutes, not seconds. Auth is off and Docker binds to 127.0.0.1 only — fine here, never expose it.

"I want this on my phone and laptop, every day" — one person, one server

You need a small VPS and a domain. Caddy gets the TLS certificate for you.

cat > .env <<'ENV'

EMAILSERVER_DOMAIN=mail.example.com POSTGRES_PASSWORD=... EMAILSERVER_API_TOKEN=... CREDENTIAL_ENCRYPTION_KEY=... SESSION_SECRET=... ENV docker compose -f docker-compose.single-user.yml up -d

Every value from openssl rand -base64 32; the API token must be at least 32 characters or the server refuses to start. What you need: a VPS with ~2 GB RAM and disk for roughly 25 MB per 1,000 messages, a domain, and an app password per mailbox. What to expect: works with anything that sends an Authorization header — Claude Code, Cursor, mcp-remote. It will *not* work with the claude.ai or ChatGPT web connectors, which negotiate OAuth and cannot send a static token. If you want those, use the next one.

"My family/team should each have their own" — a few people

Google OAuth, so each person signs in as themselves and sees only their own mailboxes.

docker compose -f docker-compose.production.yml up -d

What you need: everything above, plus a Google Cloud OAuth Web application with the two redirect URIs listed under Deployment modes. What to expect: an unverified-app warning until you submit the consent screen, and a 100-user cap while unverified — neither matters at this size.

Set `REGISTRATION_MODE=allowlist`. With open, any Google account on

earth can register on your server and attach mailboxes, and

ALLOWED_GOOGLE_EMAILS is never read. Tenant isolation still keeps strangers

out of *your* mail, but they get an account on your box. This is the easiest

thing to get wrong on a public host.

"Could this be internal infrastructure?" — 500-person company

Honestly: not yet, and here is exactly what is missing rather than a maybe.

What works today. Run it for one team as a pilot using the Google setup above. Multi-tenancy is real and enforced at the query level — every row is owner-scoped, and ownership comes from the authenticated token rather than anything a caller supplies. Mailbox credentials are encrypted at rest and never returned. Attachment binaries are never stored.

What blocks a company-wide rollout.

If you are that person: the pilot is genuinely worth running, and the honest pitch internally is "a search index over our own mail, on our own hardware, that an assistant can use" — not "an approved platform".

Mailbox credentials, whichever setup you pick

Signing in to this server grants access to nothing. Each mailbox is connected separately:

• Gmail — either an app password over IMAP, or the Gmail OAuth flow via begin_gmail_connection, which uses the Gmail API instead and survives label changes better.
• Microsoft 365 / Exchange Online — OAuth only, via begin_microsoft_connection. Microsoft accepts neither a password nor an app password for these mailboxes. See Connecting Microsoft 365.
• Everything else — an app password from the provider's security settings. Never your login password.

Connecting Microsoft 365 / Exchange Online

Microsoft mailboxes are connected the way Gmail is: you sign in at Microsoft and approve what this server may do, and the server keeps only the resulting refresh token, encrypted. That needs one app registration, made once per ser