imap-mcp

A generic IMAP → MCP server on Cloudflare Workers. It indexes a mailbox into Cloudflare's storage on a cron, then serves it to an MCP client as search, retrieval and narrow write tools — so a model can answer questions against fifteen years of mail without the mailbox itself being in the loop on every query.

Contributions are welcome; there is no support commitment. The project is run against one personal iCloud mailbox, and it is generic by design rather than by ambition — host, port and credentials are configuration, not constants — with a second provider (Gmail, #42) on the way to being exercised. Deploy your own instance from your own fork; a release is the signal that something worth merging has landed.

                        ┌─────────────────────────────┐
     IMAP over TLS      │  imap-mcp (one Worker)      │
   ┌──────────────┐     │                             │
   │   mailbox    │ ◀──▶│  sync half   src/sync       │
   │   (iCloud)   │     │  cron + queues, owns creds  │
   └──────────────┘     │      │ writes    ▲ writes,  │
                        │      ▼           │ audited  │
                        │  ┌──────────────────┐       │
                        │  │ D1 (+FTS5), R2   │       │
                        │  └──────┬───────────┘       │
                        │         │ reads             │
                        │         ▼                   │      ┌──────────────┐
                        │  MCP half    src/mcp        │◀────▶│  MCP client  │
                        │  auth gate, tools, audit    │ HTTP │              │
                        └─────────────────────────────┘      └──────────────┘

Six tools: search_messages, get_message, get_thread, flag_message, move_message, create_draft. Bodies leave one at a time, capped, inside an untrusted-content envelope; there is no send and no delete, structurally — the codebase contains no SMTP client and no delete path. Every write is audited. docs/architecture.md is the full design essay.

Deploy

What it costs, before you click: you need the Workers Paid plan (US$5/month at time of writing). Not for Queues — that has been available on the free plan since February 2026 — but for CPU: the free plan caps a Worker at 10 ms of CPU per invocation, and parsing a message's MIME, decoding its attachments and extracting its text does not fit in that. Paid raises the cap to 30 seconds. Everything else fits comfortably in the paid plan's included usage for one mailbox. You also need a mailbox app-specific password; on iCloud it grants full mailbox access including SMTP send, so treat it like the account password.

The button provisions the database, queues and bucket, prompts for the four values only you can supply — the mailbox host, the mailbox user, its app-specific password, and an MCP API key of your choosing — and deploys. Migrations run inside the deploy script, so the schema is applied on the first deploy and on every redeploy after you merge an upstream change. You get a working endpoint authenticated by the API key; putting Cloudflare Access in front of it is an optional, documented upgrade. The button deploys main; deploying a tagged release instead means putting /tree/<tag> on the button URL yourself, until the first by-hand button verification confirms tags work there.

docs/deploy.md is the full guide — the button path, the manual path, and the configuration reference. docs/authentication.md covers the two auth modes and the trade between them.

Deployed and not sure it is working? Ask it:

curl -s -H "Authorization: Bearer $MCP_API_KEY" https://<worker>.workers.dev/status | jq

docs/observability.md reads that document line by line, and covers the logs, the queues, and what a stalled backfill looks like.

Related MCP server: stalwart-mail-mcp

Quickstart, for working on it

No Cloudflare account needed — the whole suite runs offline:

pnpm install
pnpm run test        # vitest: workerd + a scripted-IMAP-server protocol suite
pnpm run lint        # biome (lint + format)
pnpm run typecheck   # wrangler types + tsc --noEmit
pnpm run dead-code   # knip
pnpm run build       # wrangler deploy --dry-run

CONTRIBUTING.md has the rest — including the one hard requirement: a change to provider behaviour needs a test in the scripted-server harness.

Documentation

Status and roadmap

Everything below "done" is implemented and green in the test suite — a suite that runs the real protocol client against a scripted server, and the real Worker runtime against local storage. What has not happened yet is a full production run against a real mailbox on the current architecture: that is #39, and until it lands, "done" means done in the suite and the spikes, not proven in production.

Licence

MIT — see LICENSE. The IMAP protocol client is cf-imap by Exerra, also MIT; its licence text ships in the tarball but no license field is set in its package.json, so licence scanners misreport it. The build currently installs a patched fork (lswith/cf-imap) while its fixes are upstreamed — docs/architecture.md has the defect table, where each was filed, and which pull request fixes it.