Skip to main content
Glama
mcp-mail

mcp-mail

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.

Related MCP server: postfach-mcp

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

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to read, search, and manage emails via IMAP with secure, read-only access to email accounts.
      6
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to securely access IMAP mailboxes with read-focused tools for searching, reading, listing messages, and creating drafts, while deliberately preventing sending or deleting emails.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to read, search, send, reply, forward, schedule, organize, and analyze email across multiple IMAP/SMTP accounts, with drafts, provider-aware labels, real-time inbox watching, verification-code capture, and calendar extraction.
      31 npm
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to read IMAP mailboxes and create drafts without sending them. Supports multiple accounts and folders, read-only message fetching, and search, with sending deliberately disabled so drafts are reviewed and sent manually.
      MIT