English · Italiano

Mail MCP Suite

A self-hosted, security-focused mail bridge for MCP clients. It combines a strict read-only IMAP server with approval-gated sending, scheduling, and IMAP moves.

The suite is Docker-first and exposes two independent Streamable HTTP MCP endpoints:

• Mail Reader — search and read allowlisted mailboxes without changing flags;
• Mail Actions — create proposals for sends, schedules, moves, restores, and cancellations;
• Mail Worker — a non-MCP service that persists proposals and executes them only after a human confirms them.

Confirmation happens in the chat itself on hosts that support MCP Apps — Claude web and Desktop, ChatGPT, Cursor, VS Code Copilot — and on the browser approval page everywhere else. Both read the proposal from the Worker and require the same human approval secret. See docs/clients.md.

Choose the smallest tool that fits

This suite is useful when you specifically need both reading and actions, remote MCP access, persistent scheduling, and a hard approval boundary.

For simpler use cases, prefer a smaller existing project:

• nikolausm/imap-mcp-server for a broad single-server IMAP workflow;
• samihalawa/mcp-server-smtp as an SMTP-oriented conceptual reference. Its repository did not declare a license when this documentation was written, so review its terms before reuse.

For inbox organization, prefer deterministic Sieve, ManageSieve, provider, or Roundcube filters. Use a scheduled LLM task for a read-only digest. AI-driven moves are available only as an advanced, interactive, approval-gated workflow.

See Acknowledgements and prior art.

Security properties

• The Reader opens mailboxes read-only and exposes no write tool.
• Mailbox access is restricted by an exact allowlist.
• The Actions MCP has no IMAP or SMTP credentials.
• The Worker is not an MCP server.
• Every send, schedule, move, and restore starts in pending_approval.
• Approval requires a human review of the stored proposal, an independent human secret, and a signed CSRF field.
• No MCP tool can approve a proposal, in chat or otherwise; the message body and the approval secret never pass through the LLM host.
• The Worker does not retry ambiguous SMTP deliveries or IMAP moves.
• There is no delete or Trash tool.
• Compose binds to 127.0.0.1 by default.
• Reader and Actions use separate bearer tokens and can use separate Cloudflare Access applications.
• Email fields are explicitly marked as untrusted content for the agent.

These controls reduce risk; they do not make an LLM a trusted mail operator. Read SECURITY.md before connecting a real mailbox.

Components and ports

Component	Default endpoint	Credentials held
Reader	http://127.0.0.1:3333/mcp	IMAP, Reader MCP token
Actions proxy	http://127.0.0.1:3334/mcp	Actions MCP token
Actions core	internal Docker network	queue API token, Actions MCP token
Worker and approval UI	http://127.0.0.1:7337	SMTP, move IMAP, queue, approval secrets

The architecture is documented in docs/architecture.md. Every environment variable is documented in docs/configuration.md.

Quick start

Requirements: Docker Compose v2 and a mail account offering IMAP and SMTP over TLS. Node.js is needed only to build from source or run the checks locally.

The whole stack is configured by one file. Passwords are not in it: they are Docker secrets, mounted only into the services that need them.

1. Configuration. Copy the example and edit it — mail hostnames, user, sender, mailbox names, and APPROVAL_TIMEZONE:

cp config/mail-mcp.env.example .env
mkdir -p local-config/secrets
chmod 600 .env
chmod 700 local-config local-config/secrets

2. Secrets. Create the seven files listed in secrets/README.md, one value per file. Generate each machine token independently, and use a separate human passphrase for approval_secret:

openssl rand -hex 32

3. Start. Point MAIL_MCP_IMAGE in .env at a published image:

MAIL_MCP_IMAGE=ghcr.io/federicokalik/mail-mcp-suite:3.0.0

docker compose config
docker compose pull
docker compose up -d

To build from source instead, add the build override:

npm ci --ignore-scripts && npm run check
docker compose -f compose.yaml -f compose.build.yaml build
docker compose up -d

4. Check.

curl --fail http://127.0.0.1:3333/healthz
curl --fail http://127.0.0.1:3334/healthz
curl --fail http://127.0.0.1:7337/healthz

Follow docs/installation.md for permissions, credential verification, LAN binding, backups, and uninstall.

MCP tools

Reader

Tool	Effect
mail_list_mailboxes	List only configured mailboxes
mail_search	Search and return headers
mail_get_message	Read one body without marking it seen

Actions

Tool	Effect
mail_send	Create an immediate send proposal
mail_schedule	Create a scheduled send proposal
mail_delivery_list / mail_delivery_get	Inspect send metadata and status
mail_delivery_cancel	Cancel a proposal that has not been claimed
mail_move_propose	Create an approval-gated IMAP move proposal
mail_move_list / mail_move_get	Inspect move metadata and status
mail_move_cancel	Cancel a move proposal that has not been claimed
mail_move_restore	Propose an approval-gated reversal

Actions returns an approval URL. The operation does not become active until the user reviews the page and enters the approval secret.

Remote access and Claude

Do not expose the HTTP ports directly to the Internet. The recommended setup uses three Cloudflare Tunnel hostnames, three default-deny Access applications, and Managed OAuth for the two MCP endpoints:

• Cloudflare Tunnel and Access guide
• Claude and other MCP clients

Cloudflare's official API MCP server can inspect and configure Cloudflare resources through OAuth. The guide includes a least-privilege prompt and a validation plan.

Filters and scheduled digests

docs/filters-and-digests.md explains the recommended order:

1. deterministic server-side filters;
2. a read-only scheduled digest;
3. optional interactive move proposals.

Digest-only Claude Cowork prompts are provided in English and Italian. They connect only to mail-reader and perform no mailbox mutations.

Development

npm ci --ignore-scripts
npm run check
npm run smoke

npm run smoke starts temporary loopback processes and never connects to a real mail server or sends mail.

See CONTRIBUTING.md before submitting changes.

Limitations

• One mail identity per deployment.
• Plain-text message bodies and recipients are stored in the outbox volume.
• No attachment download tool.
• No HTML send body; outgoing content is plain text.
• No automatic retry after ambiguous delivery or move outcomes.
• No deletion, Trash, spam classification, or autonomous sorting.
• Sent-folder copies are optional because SMTP acceptance and IMAP append are separate operations.

License

Copyright holders license this project under the GNU Affero General Public License v3.0 only, SPDX identifier AGPL-3.0-only.

If you modify the software and offer it over a network, provide users the Corresponding Source required by section 13 of the AGPL.