Skip to main content
Glama
README.md
# Email MCP for Claude – on your own Cloudflare Worker

Give Claude (claude.ai, Claude Desktop, Claude Code, scheduled tasks) secure access to **your own IMAP mailboxes**: read, search, draft, manage and – if you allow it – send email. Runs as a single Cloudflare Worker on your **own free Cloudflare account**. Nobody else ever sees your passwords.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/Richard4224/cloudflare-email-mcp)

*Deutsch: Kurzfassung [unten](#deutsch-kurzfassung).*

## Features

- **Any IMAP provider** with password/app-password login (presets for Yahoo and Gmail, everything else auto-detected via the Thunderbird autoconfig database or entered manually).
- **Several mailboxes in one Claude connection.** Claude picks the mailbox per call or searches all of them at once (`account: "all"`).
- **Permissions per mailbox** (read / manage / drafts / send) **and per Claude connection** (you choose the maximum when connecting).
- Reading **never marks mail as read.** Trash instead of permanent delete. Daily send limit.
- Only you can connect: login through **Cloudflare Access** (one-time PIN to your email) in front of the consent page and the settings page.
- Mailbox passwords are stored **AES-GCM encrypted** in D1. You enter them only on your Worker's settings page, never in a chat.

| Tool | Permission | What it does |
|---|---|---|
| `list_accounts` | read | Mailboxes and permissions of this connection |
| `list_folders` | read | Folders with message/unread counts |
| `list_emails` | read | Newest emails (headers only), `account: "all"` supported |
| `search_emails` | read | Search by from/to/subject/text/date/flags |
| `read_email` | read | Text body (HTML converted), attachment list |
| `get_attachment` | read | One attachment up to 1 MB (images, text, PDF …) |
| `mark_emails` | manage | Read/unread, flagged |
| `move_emails` | manage | Move to another folder |
| `trash_emails` | manage | Move to trash (never permanent) |
| `create_draft` | drafts | New mail or reply in the drafts folder |
| `send_email` | send | Send via SMTP, copy to "Sent" |

## How it works

```
Claude ──OAuth 2.1──▶ your Worker (https://email-mcp.<subdomain>.workers.dev)
                        /authorize  → Cloudflare Access login → consent (choose permissions)
                        /settings   → add mailboxes (app password), permissions, disconnect all
                        /mcp        → MCP tools ──IMAP 993 / SMTP 465·587 (TLS)──▶ your mail provider
                        KV: OAuth tokens · D1: mailboxes (passwords encrypted)
```

## Setup (about 15 minutes)

You need: a free [Cloudflare](https://dash.cloudflare.com/sign-up) account, a GitHub account, and an **app password** for your mailbox (Yahoo, Gmail, iCloud and others require one; normal passwords don't work for IMAP).

### 0. (Optional) A subdomain without your name

Your Worker URL is `https://email-mcp.<subdomain>.workers.dev`, and the subdomain defaults to your account name. To change it, go to **Workers & Pages → "Your subdomain" → Change** *before* deploying.

### 1. Enable Zero Trust and one-time PIN login

1. Dashboard → **Zero Trust**. Choose a team name (it appears in the login URL, so pick a neutral one) and the **Free** plan. Cloudflare asks for payment details even for the free plan, but does not charge.
2. Zero Trust → **Settings → Authentication → Login methods → Add new → One-time PIN**.

### 2. Create the Access application (OIDC)

Zero Trust → **Access → Applications → Add an application → SaaS**:

1. Name: `Email MCP`. Authentication protocol: **OIDC**. Click **Add application**.
2. **Redirect URL:** `https://email-mcp.<subdomain>.workers.dev/callback`
3. Scopes: `openid`, `email`, `profile`.
4. **Policy:** Action *Allow* → Include → **Emails** → your email address.
5. **Login methods:** only *One-time PIN*.
6. Copy **Client ID, Client secret, Authorization endpoint, Token endpoint, Key endpoint**. You need them in step 3.

### 3. Deploy

Click **Deploy to Cloudflare** above. Cloudflare copies this repo to your GitHub, creates the KV namespace and the D1 database, and asks for the secrets:

| Secret | Value |
|---|---|
| `OWNER_EMAILS` | Your email address (the one in the Access policy) |
| `SESSION_SECRET` | Random string, e.g. `openssl rand -hex 32` |
| `MAILBOX_KEY` | Random string, e.g. `openssl rand -hex 32`. **Keep it.** Changing it makes stored passwords unreadable |
| `ACCESS_CLIENT_ID` / `ACCESS_CLIENT_SECRET` | From step 2 |
| `ACCESS_AUTHORIZATION_URL` / `ACCESS_TOKEN_URL` / `ACCESS_JWKS_URL` | Authorization / Token / Key endpoint from step 2 |

Keep the Worker name `email-mcp`, or adjust the redirect URL from step 2 to match. From now on every push to `main` of your copy deploys automatically. Recommended under **Worker → Settings → Builds**: set the build command to `npm test` and disable preview builds.

### 4. Add your mailboxes

Open `https://email-mcp.<subdomain>.workers.dev/settings`, log in with the one-time PIN, and add a mailbox with its app password. Tick the permissions Claude may use for it. The connection is tested before saving.

### 5. Connect Claude

- **claude.ai / Desktop:** Settings → Connectors → *Add custom connector* → `https://email-mcp.<subdomain>.workers.dev/mcp`
- **Claude Code:** `claude mcp add --transport http email https://email-mcp.<subdomain>.workers.dev/mcp`

When connecting, the consent page lets you limit what this connection may do (e.g. no sending).

<details>
<summary>Manual setup without the button</summary>

1. Fork this repo, then run `npm install` and `npx wrangler login`.
2. Run `npx wrangler deploy`. KV and D1 are created automatically on the first deploy.
3. For every secret from step 3, run `npx wrangler secret put <NAME>`.
4. Optional: dashboard → Worker → Settings → Builds → connect your fork for automatic deploys. Do the first deploy with wrangler, because the default build token cannot create D1 databases.
</details>

## Security model

- **Who can connect:** only someone who passes your Cloudflare Access policy, i.e. receives the one-time PIN at your address. The Worker additionally checks the email against `OWNER_EMAILS`. OAuth tokens are only issued to `claude.ai`/`claude.com` and localhost callbacks.
- **Where things live:**
  - OAuth tokens of claude.ai connectors are stored by Anthropic for your Claude account; Claude Code keeps them on your machine.
  - The Worker stores token hashes in KV and mailbox passwords AES-GCM-encrypted in D1, with `MAILBOX_KEY` as the key.
- **Your accounts are the keys:** whoever controls your Cloudflare account controls the Worker; whoever controls your Claude account can use the connector. Enable **2FA** on both, and on the mailbox that receives the one-time PIN. Disconnect everything any time on `/settings` ("disconnect all Claude connections").
- **Untrusted content:** email bodies are marked as untrusted data for Claude. Destructive tools are annotated so Claude asks first. Keep "always ask" enabled for `send_email` in Claude.
- **Hardening:** no JavaScript on the pages, strict CSP, CSRF tokens, `__Host-` cookies. Mail server hosts are validated (no IPs/internal names, only ports 993/465/587, TLS only).

## Limits and known gaps

- **Not supported:** Outlook/Hotmail/Microsoft 365 (OAuth-only IMAP), Proton (local Bridge only), Tuta (no IMAP).
- Workers Free plan allows 10 ms CPU per request. Only text parts are loaded, and attachments are limited to 1 MB.
- Every tool call opens a new IMAP connection (≈1–4 s depending on the provider).
- Some providers email you once when a new app password is first used. That's expected.
- The settings and consent pages are currently in German.

## Development

```bash
npm install
npm run check          # generate types, type-check, tests (incl. full OAuth → MCP flow)
```

Local Worker: create `.dev.vars` (git-ignored) with `OWNER_EMAILS`, `SESSION_SECRET`, `MAILBOX_KEY` and `DEV_LOGIN_EMAIL=<same address>`. The dev login skips Access and works on localhost only. Then run `npx wrangler dev --port 8788 --ip 127.0.0.1`. End-to-end test against a real mailbox: put `E2E_EMAIL` / `E2E_PASSWORD` in `.e2e.vars` and run `node scripts/e2e-local.mjs [--write]`. It prints metadata only.

Built with [`@cloudflare/workers-oauth-provider`](https://github.com/cloudflare/workers-oauth-provider), the [Agents SDK](https://developers.cloudflare.com/agents/) MCP handler, [imapflow](https://github.com/postalsys/imapflow) and [postal-mime](https://github.com/postalsys/postal-mime).

## Deutsch (Kurzfassung)

Ein eigener MCP-Server auf deinem **kostenlosen Cloudflare-Konto**, über den Claude auf deine IMAP-Postfächer zugreift: lesen, suchen, Entwürfe, verwalten und, wenn du es erlaubst, senden. Nur du kommst rein, über Cloudflare Access mit Einmal-Code an deine Adresse. Deine Passwörter liegen verschlüsselt auf deinem Worker.

Einrichtung wie oben:
1. Zero Trust aktivieren und den Einmal-Code-Login hinzufügen.
2. Eine Access-App vom Typ SaaS/OIDC anlegen, mit Callback `…/callback` und der Regel „nur meine Adresse“.
3. Auf **Deploy to Cloudflare** klicken und die Secrets eintragen.
4. Auf `/settings` Postfächer mit App-Passwort hinzufügen.
5. In Claude den Connector `…/mcp` hinzufügen.

## License

MIT