claude-mail-mcp
Self-hosted IMAP/SMTP/CalDAV connector for Claude — for everyone whose mailbox isn't on Google.
claude-mail-mcp is a Streamable-HTTP MCP server that bridges Claude to your mailbox over the standard protocols IMAP, SMTP and CalDAV. You install it on your own server, store your mailbox credentials in a .env file, and from then on Claude works directly against your real inbox and calendar — no detour through a third-party API, no SaaS middleman, no vendor lock-in. Works with Mailbox.org, Fastmail, iCloud, Mailcow, iRedMail, Migadu, Nextcloud, your own Postfix box — anything that speaks RFC-compliant IMAP/SMTP.
13 tools for mail and calendar
9 mail tools (folders / messages / search / get / send / draft / mark-read / move / delete) plus 4 calendar tools (calendars / events / create-event / find-free-slot). Real server-side IMAP search, not 'load everything and filter'. Free-slot search across multiple calendars with optional working-hours window.
Provider-agnostic
Mailbox.org, Fastmail, iCloud, Gmail, Mailcow, iRedMail, Migadu, Nextcloud — anything that speaks IMAP/SMTP and optionally CalDAV works. The README lists app-password links and hostnames for the major providers ready to copy-paste.
Safe defaults
delete_message is documented as destructive so Claude.ai surfaces a confirmation step in the UI. For reversible workflows: move_message to a Trash folder. create_draft as a review step instead of direct send.
MIT-licensed
Fork, modify, commercial use — all allowed. The IMAP client, the MCP tool registry and the OAuth shim are cleanly separated; if you want to build a similar connector for CardDAV, JMAP or Matrix, the structure here is a clean template.
Why this exists
Anthropic's connector store offers exactly one email option: Gmail. If your mailbox lives on Mailbox.org, Fastmail, iCloud or your own server, you're out of luck. Which is absurd — IMAP/SMTP have been open standards since the 90s, and CalDAV has been the de-facto calendar standard outside of Google for over a decade.
claude-mail-mcp closes that gap: your mailbox stays where it is, the server runs on your infrastructure, and Claude only sees what you explicitly release via tool calls.
Architecture
Express 5 as the HTTP layer, the official @modelcontextprotocol/sdk for tool registration. IMAP via imapflow with one long-lived connection and per-mailbox locking (so parallel tool calls don't collide on the IMAP SELECT state). SMTP via nodemailer with optional best-effort copy to the Sent folder. CalDAV via tsdav, iCal parsing via ical.js. Streamable-HTTP transport, compatible with Claude.ai web and Claude Desktop.
Authentication against the mailbox uses classic IMAP/SMTP credentials in the .env file — app-specific passwords for providers with two-factor auth (Gmail, iCloud, Fastmail). The MCP endpoint itself is gated by a Bearer token, fronted by the same OAuth shim as claude-meta-mcp so Claude.ai can add the connector through the normal 'add custom connector' flow.
What you need
A Linux VPS with Node 20. An IMAP/SMTP mailbox (for 2FA providers: app-specific password — the README lists direct links to the app-password pages for Mailbox.org, Fastmail, iCloud and Gmail). Optionally a CalDAV URL for the calendar — if not set, the server starts mail-only. nginx + TLS certificate for the connector domain. Setup time: about 15 minutes from git clone to first tool call.
Roadmap
v0.2: multi-tenant with SQLite-backed token store, so one deployment can serve multiple users. v0.3: threading view (list_threads), attachment download as base64, iMIP invitations via SMTP when create_event has attendees. v0.4: CardDAV (contacts), JMAP support for Fastmail power users. v1.0: audit log, Prometheus metrics, rate limiting.
Do I need programming skills to install it?
Basic Linux knowledge is enough. The deployment guide in the repo is written as a step-by-step walkthrough — git clone, npm install, fill the .env, pm2 start. The most annoying part is usually getting the app-specific password from the mail provider, for which the README has direct links.
Does this work with Claude's free plan?
Custom MCP connectors require a paid Claude plan (Pro or higher) — that's an Anthropic restriction, unrelated to this repo.
Do I need CalDAV?
No. If CALDAV_URL is empty, the server simply doesn't register the four calendar tools — mail still works. That's the default config for mail-only providers.
How many mailboxes can one deployment serve?
In v0.1: exactly one. One install = one .env = one mailbox. Multi-tenant is coming in v0.2 with a SQLite-backed token store. To serve multiple mailboxes today, deploy the server once per mailbox (separate port, separate subdomain each).