mailindex-mcp

# mailindex-mcp

[![release](https://img.shields.io/github/v/release/alexanderkrauck/mailindex-mcp?sort=semver)](https://github.com/alexanderkrauck/mailindex-mcp/releases)
[![image](https://img.shields.io/badge/ghcr.io-mailindex--mcp-blue?logo=docker&logoColor=white)](https://github.com/alexanderkrauck/mailindex-mcp/pkgs/container/mailindex-mcp)
[![CI](https://github.com/alexanderkrauck/mailindex-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/alexanderkrauck/mailindex-mcp/actions/workflows/ci.yml)
[![licence: MIT](https://img.shields.io/badge/licence-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-19%20tools-8A2BE2)](#mcp-tools)

**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.

![Claude answering a question about a mailbox through this server](docs/demo.gif)

<sub>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.</sub>

## Why this instead of the other email MCP servers

|  | This project | Typical email MCP |
|---|---|---|
| Can it change anything | Move, mark, delete, draft, manage folders — in bulk, by search | Read-only, or one message per call |
| Search | Own PostgreSQL index, GIN full-text, stemmed across languages | Live IMAP `SEARCH` per call |
| Result completeness | Exact `total_count`, signed cursors, per-account coverage | Whatever the folder returned |
| Attachments | Text extracted and indexed at sync time (PDF, DOCX, XLSX, PPTX, OCR) | Base64 into the model's context, or not at all |
| Attachment binaries | Never stored; refetched through a 5-minute signed URL | Stored on disk or inlined |
| Transport | Remote HTTP endpoint | Local stdio process on your machine |
| Setup on the client | Paste a URL | Install a runtime, edit config JSON, store credentials locally |
| Users | Multi-tenant, every row owner-scoped | Single user |
| Tool surface | 19 tools, all annotated | Frequently 40+ |

**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.

```bash
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`](https://github.com/alexanderkrauck/mailindex-mcp/pkgs/container/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.

```bash
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:

```bash
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.

```bash
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.

<details>
<summary>Or over HTTP, if you prefer a shell</summary>

```bash
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
  }'
```

</details>

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.

```bash
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.

```bash
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.

```bash
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](#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.**

| Gap | Why it matters |
|---|---|
| Login is Google OIDC onl