kays-mail-mcp

Read-only email access for your agents, hosted on your own server.

Search mail, read messages and retrieve attachments through a standard HTTP MCP endpoint. Works with IMAP providers, including iCloud Mail and custom domains hosted by iCloud. Thunderbird is not required.

Status: early pre-release. Synthetic tests cover mail handling, setup and a real Keycloak/OAuth container flow. Real-mailbox and hosted-client connections still need verification for each installation. No independent security audit has been performed.

Quick start

On a Linux server with Docker Engine, Docker Compose v2 and Python 3.11+:

git clone https://github.com/kayroye/kays-mail-mcp.git
cd kays-mail-mcp
./setup.sh

The script asks for your mail account, two HTTPS hostnames, and a new login email/password. It generates private configuration outside the checkout and starts the services. Mail passwords are entered through hidden prompts.

For a public Cloudflare Tunnel connection, configure the tunnel routes described in the setup guide, then run:

./setup.sh --public

You still need to supply mail credentials and authorize your domain. Setup does not change mail delivery records or require an OpenAI/Anthropic API key.

Related MCP server: MailBridge MCP

Connect a client

In a client supporting remote HTTP MCP and OAuth, add:

https://your-mail-hostname.example/mcp

Complete the browser login using the email/password you chose during setup. Allow the client's OAuth callback URL in your private configuration; see client setup.

For Codex CLI:

codex mcp add mail --url https://your-mail-hostname.example/mcp
codex mcp login mail

For Claude Code:

claude mcp add --transport http mail https://your-mail-hostname.example/mcp

Use Claude Code's /mcp menu to authenticate. Hosted clients have their own connection settings and callback URLs; support depends on their MCP and OAuth capabilities. This is a private server connection, not an app-store listing.

Tools

Message retrieval uses mailbox, UID and UIDVALIDITY. Search returns the identity you need; repeat the search if the mailbox identity changes.

Security and data

• The tool surface has no sending, deletion, moving or flag-changing operations.

• Mailboxes are selected read-only; body fetches use BODY.PEEK.

• IMAP uses certificate-verified TLS and a server-controlled folder allowlist.

• Keycloak handles email/password login; FastMCP handles the OAuth bridge.

• Only the configured immutable owner identity can access mail.

• Mail and OAuth state remain on your server. Messages requested by an agent are transmitted to that agent's provider. Cloudflare handles proxied HTTPS traffic.

• Email content is untrusted input. Read-only mail access does not prevent an agent from disclosing content through another tool.

See the security policy and operations guide for boundaries, backups, upgrades, revocation and recovery.

Development

python3.12 -m venv .venv
.venv/bin/pip install --require-hashes -r requirements-dev.lock
.venv/bin/pip install --no-deps --no-build-isolation -e .
.venv/bin/ruff check .
.venv/bin/mypy
.venv/bin/pytest
.venv/bin/python tests/integration/smoke.py  # disposable Docker identity/TLS test

Tests use synthetic mail and identity fixtures. The real IMAP test is opt-in and requires a disposable mailbox; never put real credentials into tests or issues.

Attribution

Based on ares952/MCPGenericIMAP, used under the MIT License. This repository starts with fresh Git history. See UPSTREAM.md and LICENSE.