mailcow MCP

A self-hosted remote MCP server for mailcow. Users connect their mailbox to any MCP client (Claude, Cursor, VS Code, Claude Code, …) by URL and sign in with their mailcow account. An AI agent can then send, draft, read and follow up on email: attachments (including PDFs rendered on the server), reply tracking, rescuing replies from spam and quarantine, delivery status and contacts.

Status: 0.x. Runs on a production mailcow server; tested against a real Dovecot/Postfix and a mock of mailcow's API. Configuration may still change before 1.0 (see docs/upgrading.md).

This is a community project. It is not affiliated with or endorsed by the mailcow team or The Infrastructure Company GmbH.

How it works

• No installs, no passwords handed to third parties. Add https://mcp.example.com/mcp to the client, click Sign in with mailcow, sign in on mailcow's own login page (2FA included). mailcow-mcp creates an app password named MCP: <app> (…) for IMAP, SMTP and contacts only; the user sees it in mailcow and can delete it any time.

• Each connection acts only as the mailboxes signed into it: one or several (a user can add their other mailboxes to the same connector).

• The mailcow API key never sits in an internet-facing process. A small internal broker holds it and can only create and delete app passwords for mailboxes that signed in, and read their quarantine and delivery log, proven by signed capability tokens.

• Any MCP client works: Streamable HTTP with the standard MCP authorization (OAuth 2.1, dynamic client registration, PKCE).

• Generic mode runs against any IMAP/SMTP server with a password sign-in.

• Drafts only, if you like: with SENDING=drafts_only no tool sends mail; the assistant writes drafts and people send them from their mail app.

Tools: list_mailboxes, add_mailbox, remove_mailbox, send_email, save_draft, send_draft, delete_draft, list_folders, list_messages, search_messages, read_message, get_attachment, find_replies, get_thread, mark_messages, move_messages, list_spam, rescue_from_junk, release_from_quarantine, delete_from_quarantine, delivery_status, my_addresses, find_contacts. See docs/tools.md.

Related MCP server: OutreachEmailMCP

5-minute quick start (mailcow)

On the mailcow server, with a DNS record mcp.example.com pointing to it:

sudo mkdir -p /opt/mailcow-mcp && sudo chown "$USER" /opt/mailcow-mcp && cd /opt/mailcow-mcp
curl -fsSL https://github.com/nitramxx/mailcow-mcp/releases/latest/download/mailcow-kit.tar.gz | tar xz
sudo ./setup-mailcow.sh --hostname mcp.example.com      # read-only: checks and shows what it will do

It checks each step against mailcow (DNS, certificate, OAuth2 app, API key, Fail2ban allowlist) and lists what's left, with exact values. Once the mailcow-side steps show ✓:

sudo ./setup-mailcow.sh --hostname mcp.example.com --apply --restart   # writes the config, starts

Updating later: sudo ./setup-mailcow.sh update.

The full guide, with a check and troubleshooting for every step: docs/deploy-mailcow.md. Connecting clients: docs/clients.md.

Supported mailcow versions: 2026-07 and later.

Security model in short

• Two containers from one image: the app (behind mailcow's nginx; no API key) and the broker (internal network only; the API key; a fixed list of mailbox-scoped operations).

• Access tokens last an hour, refresh tokens rotate, credentials are encrypted at rest, tokens are stored as hashes. Connections end after 30 days without use.

• Email content returned to the model is marked as untrusted to blunt prompt injection; sending and releasing tools are marked destructive so clients ask first. Don't choose "always allow" for them.

• SMTP is always authenticated; mail server certificates are verified (TLS_VERIFY=false exists for testing only).

Details, threat model and what is stored: docs/security.md.

Documentation

• Deploy next to mailcow · generic mode with Caddy

• Connect clients · Tools · Configuration

• Security · Upgrading

• Uživatelská příručka (česky)

• For contributors: CONTRIBUTING.md, mailcow API notes

Development

Requires uv; integration tests need Docker.

uv sync
scripts/check              # lint, format, types, tests

Run it locally in generic mode against any IMAP server, then connect an MCP client (for example MCP Inspector) to http://localhost:8090/mcp:

mkdir -p data
MODE=generic PUBLIC_URL=http://localhost:8090 TRUSTED_PROXIES=127.0.0.1 DATA_DIR=./data \
  IMAP_HOST=imap.example.org SMTP_HOST=smtp.example.org \
  ENC_KEY=$(uv run mailcow-mcp generate-key) uv run mailcow-mcp serve

License

MIT