cpanel-mail-mcp
This MCP server lets you manage and use IMAP/SMTP email accounts from an MCP client.
List accounts and IMAP folders
List recent messages with pagination and filters
Search emails by FROM/TO/SUBJECT/BODY/TEXT
Read full email headers and bodies
Download or inspect attachments as base64
View email threads by Message-ID/References
Send emails with text, HTML, attachments, and Save-to-Sent
Reply to or forward messages while preserving threading
Send RFC 5545 calendar invites
Save drafts to the Drafts folder
Mark messages read/unread and star/unstar them
Move or copy messages between folders
Soft-delete to Trash or permanently delete messages
Create, delete, and rename IMAP folders
Use multiple email accounts and choose per tool call
Retry sends safely with idempotency keys
Enforce rate limits, attachment size caps, and optional send confirmation codes
Provides tools for managing cPanel email accounts over IMAP/SMTP, including reading, searching, sending, replying, forwarding, moving, copying, flagging, deleting messages, managing folders, handling attachments, and sending calendar invites.
Integrates with Gmail via IMAP/SMTP using app passwords, enabling email management such as listing, reading, searching, sending, replying, forwarding, moving, copying, flagging, deleting messages, managing folders, and handling attachments.
Integrates with iCloud email over IMAP/SMTP, allowing users to list, read, search, send, reply, forward, move, copy, flag, and delete messages, manage folders, and work with attachments and calendar invites.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cpanel-mail-mcp show my latest 5 emails in Inbox"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cpanel-mail-mcp
MCP server for IMAP/SMTP email accounts — works with cPanel, Gmail (app passwords), Outlook, Fastmail, iCloud, or any provider that speaks plain IMAP + SMTP.
Features
22 typed MCP tools — one per operation with Pydantic input/output schemas, tool annotations (
readOnlyHint/destructiveHint/…), and actionable error messagesFull mailbox management — read, search, threading, move, copy, flag, star, delete, reply, forward, drafts, calendar invites, folder create/delete/rename
n8n / Docker ready —
MCP_AUTH_MODE=credentials: each client sends its own mailbox login per request, the server stores no passwords; Dockerfile for DokployMulti-user server mode — one instance, many users, each with their own bearer token and mailbox (per-request isolation; users.json changes apply without a restart)
OAuth 2.1 via Cloudflare Access — optional SSO (Google / GitHub / Email OTP) instead of shared bearer tokens; server exposes RFC 9728 protected-resource metadata, RFC 8414 AS metadata, and RFC 7591 DCR — proxied over CF Access SaaS OIDC
Idempotent sends — pass
idempotency_keyonsend_email/reply_email/forward_email/send_inviteto safely retry after client timeoutsPer-caller rate limiting — sliding window (send: 30/min, read: 300/min defaults), tunable per bucket
Attachment size guard — configurable cap (default 25 MB total)
Multi-account — manage multiple email accounts from different providers
Read, search, list — full IMAP support with folder browsing
Send emails — plain text, HTML, or both (multipart/alternative)
Attachments — send as base64/inline data, or by file path in local (stdio) mode
Download attachments — extract attachments from received emails as base64
Calendar invites — send proper ICS invitations with Accept/Decline buttons
Save to Sent — automatically saves sent emails to the Sent folder via IMAP
Optional send gate — configurable confirmation code to prevent accidental sends
International folders & search — UTF-7 folder names; accented search terms (
Reunión) via UTF-8 SEARCHStable message IDs — every
uidis a real IMAP UID, safe to reuse across callsAttachment flag in listings —
has_attachments/attachment_countper message, without downloading bodies
See CHANGELOG.md for what changed in each release.
Related MCP server: Email Server
Install
With uvx (recommended, no venv setup)
claude mcp add cpanel-mail \
-e CPANEL_USER=you@example.com \
-e CPANEL_PASS='your_password' \
-e CPANEL_SMTP_HOST=mail.example.com \
-e CPANEL_IMAP_HOST=mail.example.com \
-- uvx cpanel-mail-mcpWith pipx
pipx install cpanel-mail-mcp
claude mcp add cpanel-mail \
-e CPANEL_USER=you@example.com -e CPANEL_PASS='...' \
-e CPANEL_SMTP_HOST=mail.example.com -e CPANEL_IMAP_HOST=mail.example.com \
-- cpanel-mail-mcpClaude Desktop extension (.mcpb)
mcpb/ holds the one-click Claude Desktop extension ("Correo DMF"):
./mcpb/build.sh packs it into dist/cpanel-mail-dmf-<version>.mcpb. See
mcpb/README.md.
Development install (from a git checkout)
git clone https://github.com/rosauceda/cpanel-mail-mcp
cd cpanel-mail-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env # edit
cpanel-mail-mcp # runs the stdio server
# or: python -m cpanel_mail_mcpConfiguration
Three ways, in priority order:
1. EMAIL_ACCOUNTS_JSON (best for multi-account)
export EMAIL_ACCOUNTS_JSON='[
{"name":"work","user":"me@work.com","password":"...",
"smtp_host":"mail.work.com","imap_host":"mail.work.com",
"sent_folder":"INBOX.Sent"},
{"name":"gmail","user":"me@gmail.com","password":"app_pass",
"smtp_host":"smtp.gmail.com","smtp_port":587,
"imap_host":"imap.gmail.com","sent_folder":"[Gmail]/Sent Mail"}
]'2. EMAIL_ACCOUNTS_FILE
Point to a JSON file with the same shape.
3. Legacy single-account (CPANEL_*)
Backwards compatible with 0.1.x installs. See .env.example.
Account fields
field | required | default |
| no |
|
| yes | — |
| yes | — |
| yes | — |
| no |
|
| yes | — |
| no |
|
| no |
|
| no |
|
| no |
|
| no | — |
| no |
|
| no | auto-detect (SPECIAL-USE |
sso_emails is a list of external identities (e.g. Google login addresses)
that map to this account. Only used in OAuth mode: the JWT email claim is
looked up here before falling back to user. Handy when the SSO identity
differs from the mailbox address — e.g. logging in with me@gmail.com to
access me@company.com.
Loading a dev .env
The server auto-loads .env from the current working directory. Point it
elsewhere with:
export EMAIL_ENV_FILE=/absolute/path/to/.envTools
Since 0.7.0 the server exposes one tool per operation (was a single
dispatcher tool before). Every tool has a typed Pydantic input schema, an
outputSchema for structuredContent, and annotations
(readOnlyHint / destructiveHint / idempotentHint / openWorldHint)
so clients can render the right approval UI.
Every uid is a real IMAP UID (stable across calls and sessions), never a
sequence number. Tools that take a uid accept exactly one numeric UID —
ranges like 1:* are rejected. Read-only tools open folders with EXAMINE,
so read_email does not mark a message as read (use mark_read).
Every message in list_recent / search_emails / get_thread carries
has_attachments and attachment_count, read from IMAP BODYSTRUCTURE (no
bodies downloaded). Images embedded in the HTML (signature logos) don't
count; read_email lists them with embedded: true.
tool | annotations | purpose |
| read-only, idempotent | Accounts visible to caller (no secrets) |
| read-only, idempotent, openWorld | IMAP folders (UTF-7 decoded) |
| read-only, idempotent, openWorld | Paginated recent messages + flags + |
| read-only, idempotent, openWorld | IMAP SEARCH by FROM/TO/SUBJECT/BODY/TEXT |
| read-only, idempotent, openWorld | Headers + body (opt: attachments as base64) |
| read-only, idempotent, openWorld | Fetch attachments by name filter |
| read-only, idempotent, openWorld | Ancestors + replies via Message-ID/References |
| destructive, idempotent | Send new message (attachments, HTML, save-to-sent) |
| destructive, idempotent | Reply to UID, preserves References chain |
| destructive, idempotent | Forward UID (attaches original body + files) |
| destructive, idempotent | ICS calendar invite (RFC 5545, METHOD:REQUEST) |
| non-destructive | APPEND a draft to Drafts folder |
| non-destructive, idempotent, openWorld | Toggle \Seen flag |
| non-destructive, idempotent, openWorld | Toggle \Flagged flag |
| non-destructive | RFC 6851 MOVE (COPY+EXPUNGE fallback) |
| non-destructive | IMAP COPY |
| destructive | Soft-delete → Trash (or hard with |
| non-destructive | IMAP CREATE + SUBSCRIBE |
| destructive, idempotent | IMAP DELETE (must be empty) |
| non-destructive | IMAP RENAME |
Example — send with attachment + Save-to-Sent
{
"tool": "send_email",
"arguments": {
"to": "someone@example.com",
"subject": "Report",
"text": "See attached.",
"html": "<p>See <b>attached</b>.</p>",
"attachments": [
{"name": "report.pdf", "content_base64": "JVBERi0xLjc..."},
{"name": "note.txt", "content": "hi from inline"}
],
"idempotency_key": "report-2026-07-20-A"
}
}Attachment shapes accepted:
{"name": "x.bin", "content_base64": "..."}— inline base64{"name": "x.txt", "content": "hello", "mime": "text/plain"?}— inline text{"path": "/local/file.pdf", "name": "renamed.pdf"?}— read from disk. Allowed in stdio mode; in HTTP mode disabled unlessMCP_ATTACHMENT_DIRis set, and then only for files under that directory (remote callers must never read the server's own files).
Total attachment size is capped by MCP_MAX_ATTACHMENT_MB (default 25 MB).
Calendar invite times
send_invite accepts ISO 8601 with an offset (2026-10-01T10:00:00-06:00)
or a naive YYYY-MM-DD HH:MM. Naive times are read in the timezone argument
(IANA name, e.g. America/Mexico_City), else MCP_DEFAULT_TIMEZONE, else UTC.
Idempotent sends
Any of send_email, reply_email, forward_email, send_invite accept
idempotency_key. Second call with the same (caller, key) within 5
minutes returns the cached first response (idempotent_replay: true) — no
duplicate delivery on client retries, even when both calls arrive at once.
Rate limiting
Per-caller sliding window; defaults:
send bucket (send/reply/forward/invite/draft): 30 requests/min
read bucket (everything else): 300 requests/min
Tune via MCP_RATE_LIMIT_SEND_PER_MIN / MCP_RATE_LIMIT_READ_PER_MIN.
When exceeded, the tool returns a structured error with retry_after_seconds.
Reply / forward preserve threading
reply_email copies the original Message-ID into In-Reply-To and appends
it to the original References, so mail clients thread correctly. It goes to
the original Reply-To when present (else From); reply_all adds the
original To/Cc minus your own address. forward_email adds a
standard Fwd: prefix and quotes the original headers + body inline; any
attachments on the original are re-attached to the forward.
Pick an account (multi-account setup)
Every tool accepts an optional account param; omit it to use the first
configured account. In multi-user OAuth mode this field is ignored — the
account is chosen by the caller's bearer token or SSO email.
Run as an HTTP server (LXC / VPS / homelab)
By default cpanel-mail-mcp runs over stdio — your MCP client
launches it per session. To run it 24/7 as a shared HTTPS endpoint,
you have two shapes:
Docker / Dokploy + n8n (credentials mode)
The image runs in MCP_AUTH_MODE=credentials: every request carries the
mailbox login, so there are no users to register and no passwords stored
on the server. Each n8n credential is one mailbox.
docker build -t cpanel-mail-mcp .
docker run -d -p 8080:8080 \
-e CPANEL_HOST=mail.tudominio.com \
-e MCP_ALLOWED_EMAIL_DOMAINS=tudominio.com \
cpanel-mail-mcpOn Dokploy: create an Application from this repo with build type
Dockerfile, set the env vars below, and either keep it internal (n8n on the
same Dokploy reaches it as http://<app-name>:8080/mcp) or add a domain.
env var | required | purpose |
| yes | your IMAP/SMTP server ( |
| recommended | comma list of address domains allowed to log in |
| if public | extra shared secret, sent as |
| no | how long a verified login is cached (default 600) |
| no | same defaults as the cPanel setup |
In n8n: AI Agent → Tool → MCP Client Tool
Endpoint:
http://<app-name>:8080/mcp(internal) orhttps://mcp.tudominio.com/mcpServer Transport: HTTP Streamable
Authentication: Multiple Headers Auth →
X-Email-User= the mailbox,X-Email-Password= its password (plusX-API-Keyif you set one)Tools to include: All (22 tools)
Authorization: Basic base64(user:password) works as well. A login is checked
against IMAP once and cached; wrong passwords are throttled per mailbox (5 per
15 min) and globally, so the endpoint can't be used to guess passwords.
Multi-user (recommended for a team)
One instance, many users. Each person has their own bearer token, and the server enforces that they can only touch their own mailbox. Setup:
# on the server (Debian/Ubuntu LXC as root)
apt install -y curl # if not present
curl -fsSL https://raw.githubusercontent.com/rosauceda/cpanel-mail-mcp/main/deploy/install.sh | bash
# after logging out and back in (so $EMAIL_USERS_FILE is exported):
systemctl enable --now cpanel-mail-mcp
cpanel-mail-mcp admin add-user --email juan@dominio.com --host mail.dominio.com
# prompts for password → prints juan's bearer token → hand it to juan
# (add/rotate/remove take effect on the next request — no restart)Each user, in their Claude Code (the URL goes before --header):
claude mcp add --transport http --scope user cpanel-mail \
https://mcp.yourdomain.com/mcp \
--header "Authorization: Bearer <THEIR_TOKEN>"Full docs, admin CLI, migration, Cloudflare Tunnel example, hardened
systemd unit → deploy/.
Single-tenant (only you)
export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=8080
export MCP_AUTH_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(36))')"
export EMAIL_ACCOUNTS_JSON='[{...one account...}]' # or EMAIL_ACCOUNTS_FILE
cpanel-mail-mcpEndpoints:
POST /mcp— MCP Streamable HTTP transport (requires bearer token)GET /health— plainokfor reverse-proxy probes
OAuth 2.1 via Cloudflare Access (optional, for MCP clients that require OAuth)
Adds SSO on top of the multi-user mode. Cloudflare Access SaaS OIDC does the
actual user login (Google / GitHub / Email OTP); the server verifies the
resulting JWT and maps email → account. Also exposes:
GET /.well-known/oauth-protected-resource(RFC 9728) — root and/mcppath-suffixedGET /.well-known/oauth-authorization-server(RFC 8414) — composed metadata that adds aregistration_endpointPOST /register(RFC 7591 Dynamic Client Registration) — returns the pre-configured CF client credentials so DCR-only clients can registerWWW-Authenticate: Bearer realm="mcp", resource_metadata="..."on 401 responses
Env vars to enable:
var | purpose |
| audience tag / SaaS app Client ID |
| full CF OIDC issuer URL |
| same as above (enables the DCR proxy) |
| SaaS app Client ID |
| SaaS app Client Secret |
| public URL of this server |
Full setup (CF dashboard config, systemd env file, ingress) →
deploy/README.md.
Client compatibility
Client | Auth mode | Status |
Claude Code CLI ( | Multi-user bearer | ✅ Works |
Claude Code CLI + OAuth ( | OAuth 2.1 with static credentials | ✅ Works |
Anthropic Messages API ( | Static bearer, no OAuth flow | ✅ Works |
claude.ai Custom Connector (web) | OAuth 2.1 via CF Access OIDC | ⚠️ Beta — see below |
claude.ai Custom Connector — known issue
Custom Connectors is still marked BETA. Earlier versions (≤0.6.x) exposed a
single email dispatcher tool with a generic params: dict; Anthropic's
frontend rejected the setup with an opaque ofid_... reference before
opening the OAuth browser. In 0.7.0 the surface changed to 22 individually
typed tools with outputSchema and annotations, which may help.
If setup still fails:
Fill in the OAuth Client ID and Secreto del cliente OAuth fields from your CF Access SaaS app manually (leaving them empty relies on DCR, which we proxy but Claude's frontend may still fail on).
Contact Anthropic support with the exact
ofid_...reference from the error toast — only they can look up what specifically failed.Meanwhile use the Claude Code CLI (works fully) or the Messages API with a static
authorization_token.
Send gate (recommended when an agent has this tool)
Prevent accidental sends by requiring a shared secret:
export EMAIL_SEND_CONFIRMATION_CODE=please-sendEvery send / send_invite call must include confirm: "please-send" in
params, or the server refuses.
Security notes
.envis git-ignored. Never commit it.Prefer a dedicated mailbox (e.g.
mcp@yourdomain.com) with a small quota.If your provider supports app passwords (Gmail, Fastmail, iCloud), use one instead of your primary password.
MCP env vars end up in
~/.claude.jsonon your machine — treat that file like a keychain.
License
MIT — see LICENSE.
Available Tools
22 toolscopy_emailB
Copy a message to another folder without removing the original.
Inputs: uid (required), source_folder (required), destination_folder (required), account. Returns: ok, uid, account, new_uid, +2 more
create_folderA
Create a new IMAP folder and subscribe to it.
Inputs: folder (required), account. Returns: ok, action, folder, account, +1 more
delete_emailADestructiveIdempotent
Delete a message. Soft-delete by default (moves to Trash).
Inputs: uid (required), folder, account, permanent, +1 more. Returns: ok, uid, folder, account, +1 more
delete_folderADestructiveIdempotent
Delete an empty IMAP folder. Fails if not empty (per RFC).
Inputs: folder (required), account. Returns: ok, action, folder, account, +1 more
download_attachmentsARead-onlyIdempotent
Return message attachments as base64. Filter by filenames to save bytes.
Inputs: uid (required), folder, account, filenames. Returns: uid, folder, account, attachments
forward_emailADestructiveIdempotent
Forward a message. Subject gets Fwd: prefix; original headers quoted.
Inputs: to (required), uid (required), cc, bcc, +6 more. Returns: ok, account, message_id, recipients, +2 more
get_threadBRead-onlyIdempotent
Group messages sharing Message-ID / References / In-Reply-To headers.
Inputs: uid (required), limit, folder, account. Returns: folder, account, subject, messages, +1 more
list_accountsARead-onlyIdempotent
List email accounts this caller can act on (no secrets returned).
In multi-user OAuth mode, only the caller's own account is returned; in single-tenant mode, all configured accounts appear.
Inputs: no named parameters. Returns: accounts
list_foldersARead-onlyIdempotent
List every IMAP folder (mailbox) the account can see, UTF-7 decoded.
Inputs: account. Returns: account, folders
list_recentARead-onlyIdempotent
List the most recent messages in a folder (metadata only, newest first).
Use cursor (=previous next_cursor) to page further back in time.
Inputs: limit, cursor, folder, account. Returns: folder, account, messages, next_cursor
mark_readCIdempotent
Add the \Seen flag.
Inputs: uid (required), folder, account. Returns: ok, uid, folder, account, +1 more
mark_unreadCIdempotent
Remove the \Seen flag.
Inputs: uid (required), folder, account. Returns: ok, uid, folder, account, +1 more
move_emailBIdempotent
Move a message between folders (RFC 6851 MOVE with COPY+EXPUNGE fallback).
Inputs: uid (required), source_folder (required), destination_folder (required), account. Returns: ok, uid, account, new_uid, +2 more
read_emailARead-onlyIdempotent
Fetch full headers + body of a message. Attachments listed by name+mime.
Set include_attachments=true to also embed each attachment as base64
(respects the size limit; large attachments may push you over context).
Inputs: uid (required), folder, account, include_attachments. Returns: cc, to, uid, date, +5 more
rename_folderC
Rename an IMAP folder.
Inputs: folder (required), new_name (required), account. Returns: ok, action, folder, account, +1 more
reply_emailADestructiveIdempotent
Reply to a message. Preserves Message-ID linking + Subject Re: prefix.
reply_all=true includes the original To and Cc in the reply.
Inputs: uid (required), html, text, folder, +6 more. Returns: ok, account, message_id, recipients, +2 more
save_draftBIdempotent
Save an unsent draft in the account's Drafts folder.
Inputs: cc, to, bcc, html, +5 more. Returns: ok, error, folder, account, +1 more
search_emailsARead-onlyIdempotent
IMAP SEARCH over one field. Wraps query in quotes for IMAP.
Note: IMAP SEARCH is substring, case-insensitive on most servers, and doesn't support boolean operators. For richer queries, chain calls.
Inputs: query (required), field, limit, folder, +1 more. Returns: field, query, folder, account, +1 more
send_emailADestructiveIdempotent
Send an email. Supports HTML, attachments, and Save-to-Sent.
On retries after a client timeout, pass the same idempotency_key you
used the first time to prevent duplicate delivery.
Inputs: to (required), cc, bcc, html, +8 more. Returns: ok, account, message_id, recipients, +2 more
send_inviteBDestructiveIdempotent
Send a calendar invite (RFC 5545 ICS, METHOD:REQUEST).
Inputs: to (required), end (required), start (required), subject (required), +12 more. Returns: ok, account, message_id, recipients, +2 more
star_emailBIdempotent
Add the \Flagged (starred) flag.
Inputs: uid (required), folder, account. Returns: ok, uid, folder, account, +1 more
unstar_emailCIdempotent
Remove the \Flagged flag.
Inputs: uid (required), folder, account. Returns: ok, uid, folder, account, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Each tool targets a distinct action or resource. For example, star_email and unstar_email are opposites, and folder operations (create, delete, rename) are clearly separated. No overlapping purposes.
Most tools follow a verb_noun pattern (e.g., send_email, create_folder). However, list_recent deviates slightly (verb_adjective), but it's still intuitive and the overall pattern is consistent.
22 tools cover essential email operations without being excessive. Each tool has a clear purpose, and the number is well-scoped for a mail server.
The tool set covers email lifecycle: send, receive, search, organize folders, mark flags, and manage drafts. Missing features like spam handling are non-essential; core operations are complete.
Maintenance
Related MCP Connectors
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Gmail, Outlook, Hotmail, Microsoft 365, Yahoo, iCloud and other IMAP mailboxes: search, read, send.
Email, calendar and contacts for AI agents: Gmail, Microsoft 365 and IMAP accounts behind one API.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Related MCP Servers
- AlicenseAqualityFmaintenanceEnables email management through SMTP and IMAP protocols with support for sending emails with attachments, searching and filtering messages, replying/forwarding with threading, organizing mailboxes, and managing multiple email accounts.5737 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables email management through IMAP and SMTP protocols, supporting reading, sending, replying to emails with proper threading, and downloading attachments. Supports multiple email accounts with flexible configuration options.1BSD 3-Clause
- AlicenseNot gradedqualityCmaintenanceEnables receiving and sending email via IMAP and SMTP across multiple accounts, with tools for listing, searching, reading, replying, and managing messages.MIT
- AlicenseNot gradedqualityCmaintenanceEnables searching, reading, sending, replying to, forwarding, and organizing email across multiple SMTP/IMAP accounts.MIT