Skip to main content
Glama
mcp-mail

mcp-mail

README.md
# mcp-mail

> Read-only mail access for Claude, built for a wine agency's sales team:
> drafts only, a daily mail agent on the Claude API, CRM tools, and invoice
> filing through n8n.

An MCP server that gives a model read access to **one** IMAP mailbox and lets
it save drafts there, over Streamable HTTP, authenticated with GitHub OAuth.

**This build cannot send mail.** It has no SMTP code and no send, reply, move,
mark or delete tool. Drafts are appended over IMAP to the Drafts folder, where
you review and send them yourself from your mail client.

One process serves one mailbox. To cover several, run this image several times
with different configuration — separate containers, domains and connectors. A
client then picks the mailbox by choosing a connector, rather than by passing
an account name it might get wrong, and a compromise of one mailbox does not
reach the others.

## Email is not like other data sources

Most MCP servers expose data that sits still. A mailbox does not: **anyone in
the world can put text into it**, that text lands in the model's context, and
the same server can send mail back out. Private data, attacker-controlled
content and an outbound channel meet in one place.

This build removes the outbound channel altogether: there is no tool that can
send, so an instruction hidden in a message body has nothing to send with.
Bodies are still labelled as untrusted where they are returned, and the server
instructions tell the model that email content is data, never instructions.

## Why a GitHub OAuth app?

GitHub is only the login screen; it has nothing to do with your mail. Remote
MCP clients such as claude.ai require OAuth, OAuth requires something that
authenticates a human, and FastMCP's `OAuthProxy` deliberately stores no users
of its own. The app requests the `read:user` scope — read-only
profile, not repositories — and the only field used is your login, compared against
`ALLOWED_GITHUB_LOGINS`. FastMCP ships providers for Google, Azure, Auth0 and
others if you would rather not use GitHub; swapping is a one-line change in
`server.py`.

## Tools

**Diagnostics** — `mail_status` (connection, unread count, drafts folder),
`mail_list_folders`

**Reading** — `mail_list`, `mail_search`, `mail_get`, `mail_get_thread`,
`mail_get_attachment`. Nothing marks a message as read.

**CRM** (only when `AGENT_API_URL` is set) — `crm_sender_context`,
`crm_add_reminder`, `crm_log_exchange`, `crm_suggest`, `crm_quiet_tastings`,
and `mail_file_invoice` (with `INVOICE_WEBHOOK_URL`). They call the agency
site's `agent-mail` function, which only allows reminders, exchange notes and
suggestions a human approves; facts about a mail (Message-ID, sender, date) are
read from the mailbox, never taken from the model. Invoices go to the estate's
Drive folder through an n8n webhook that only accepts known folders.

**Drafts** — `mail_save_draft` (threaded under the original with `reply_to_uid`), into the folder the server flags as `\Drafts`
(or `DRAFTS_FOLDER`). The folder is never created.

## Setup

### 1. GitHub OAuth app

One per instance, at **Settings → Developer settings → OAuth Apps**, callback
URL `<BASE_URL>/auth/callback`.

### 2. Mailbox credentials

Standard IMAP with a username and password. For IONOS: port 993, SSL, and the host
of the account's region — `imap.ionos.fr` for IONOS France, `imap.ionos.com`
for the US. The wrong one answers "authentication failed". Gmail needs an App Password with 2FA enabled; Microsoft 365 has
disabled basic authentication and is not supported.

### 3. Run

```bash
cp .env.example .env    # then fill it in
docker build -t mcp-mail .
docker run -d --name mcp-mail-info --env-file .env \
  -v /srv/mail-info:/data -p 8080:8080 mcp-mail
```

### Clever Cloud

FS Buckets are not available to Docker applications on Clever Cloud, so deploy
with the Python runtime instead, which installs `requirements.txt` (the pinned
tree, then this package). Set, besides the variables below:

| Variable | Value |
|---|---|
| `CC_PYTHON_VERSION` | `3.12` |
| `CC_RUN_COMMAND` | `mail-mcp` |
| `MAIL_MCP_PORT` | `9000` — custom run commands listen behind the 8080 proxy |
| `CC_FS_BUCKET` | `/data:<bucket host>` |
| `FASTMCP_HOME` | `/home/bas/<app_id>/data/fastmcp` |
| `FASTMCP_CHECK_FOR_UPDATES` | `off` |

### 4. Add the connector

- **Claude Code** — `claude mcp add --transport http mail-info <BASE_URL>/mcp`
- **claude.ai / Claude Desktop** — Settings → Connectors → Add custom
  connector → `<BASE_URL>/mcp`

Note the `/mcp` suffix; the bare domain is not the endpoint.

## Configuration

| Variable | Purpose |
|---|---|
| `MAILBOX_LABEL` | Which mailbox this instance serves; appears in the server name and tool descriptions |
| `AGENT_NOM` / `AGENT_POSTE` | Daily agent only (required): the person whose mailbox this is, filled into `agent_consignes.md` |
| `AGENT_PRENOM` / `AGENT_TELEPHONE` / `AGENT_SIGNATURE` / `AGENT_STYLE` | Daily agent, optional: first name (defaults to the first word of the name), phone and signature of the drafts, personal writing habits |
| `BASE_URL` | Public URL of this instance, no trailing slash |
| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | GitHub OAuth app for this instance |
| `ALLOWED_GITHUB_LOGINS` | Who may connect; empty stops the server |
| `JWT_SIGNING_KEY` | Required. Signs client tokens and encrypts the stored OAuth state |
| `IMAP_*` | Mailbox credentials |
| `FROM_ADDRESS` / `FROM_NAME` | From header on drafts; the address defaults to `IMAP_USER` |
| `DRAFTS_FOLDER` | Drafts folder; empty uses the one flagged `\Drafts` |
| `MAX_BODY_CHARS` / `MAX_ATTACHMENT_BYTES` | Size caps on what is returned |
| `MAIL_MCP_PORT` / `PORT` | Listening port, 8080 by default; `MAIL_MCP_PORT` wins |

`.env.example` documents each one. In the Docker image the OAuth state lives
in `/data/fastmcp`; mount persistent storage on `/data`.

## Notes

IMAP is synchronous and connections go stale when idle, so each operation
opens its own short-lived connection in a worker thread. That costs a login per
call and avoids nursing a long-lived socket.

Dependencies are pinned in `requirements.lock`, installed before the package.

## Credits

Built on Jakub Pilař's original MCP mail server.

## Licence

MIT