PrivateEmail MCP
The server enables Claude to interact with Namecheap PrivateEmail mailboxes via IMAP and SMTP, providing full email management:
Account & connectivity: Check IMAP/SMTP health, view account info.
List & search: List emails in any folder with filters (date, unread), search by sender/recipient/subject/body/text.
Read emails & threads: Fetch full content (text, HTML) and attachment metadata, get conversation threads.
Send & reply: Send new emails, reply (with threading and reply-all), forward.
Drafts: Save, list, and send drafts (moved to Trash after sending).
Organize: Move, copy, delete (trash/permanent), mark read/unread/flagged.
Manage folders: Create, rename, delete IMAP folders.
Attachments: Download attachments by part index (base64 or file).
Resources & prompts: Access inbox via URIs (recent, unread, messages, folders) and use prompts (summarize, triage, draft reply, compose).
PrivateEmail specifics: Automatically archives sent emails to the Sent folder, operates over standard IMAP/SMTP.
Provides an MCP interface for Namecheap PrivateEmail, enabling mailbox management including reading inbox, searching emails, sending and replying to messages, managing folders and drafts, and handling attachments via IMAP and SMTP.
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., "@PrivateEmail MCP show me my recent inbox emails"
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.
PrivateEmail MCP
PrivateEmail MCP is a Model Context Protocol server for Namecheap PrivateEmail.
It connects to mail.privateemail.com over IMAP and SMTP so Claude Code can read inboxes, search mail, draft replies, send messages, manage folders, and work with drafts.
This server is built for the Namecheap email provider called PrivateEmail. It is session scoped by design. Everything runs while Claude Code is connected to the server. There are no background workers, schedulers, or durable campaign daemons.
Reliability notes (v1.1.4)
VPN / firewall mail-port blocks: many networks (including corporate VPNs) blackhole outbound IMAP
993and SMTP465. Direct connects then hang until the client times out. Usescripts/run-mcp-with-tunnel.sh(SSH LocalForward via a host that can reachmail.privateemail.com, defaultubee). The wrapper starts the tunnel and points IMAP/SMTP at127.0.0.1:21993/127.0.0.1:21465withPRIVATEEMAIL_TLS_HOSTNAME=mail.privateemail.com.Fail-fast timeouts:
PRIVATEEMAIL_CONNECT_TIMEOUT(default 12s) andPRIVATEEMAIL_COMMAND_TIMEOUT(default 30s) replace the old 60s hangs. Timeouts return an actionable tunnel hint instead of an ambiguous agent timeout.Dependency pin: requires
mcp[cli]>=1.6.0,<2.0.0. MCP Python SDK 2.x removed FastMCP (mcp.server.fastmcp); an unpinned install pulls 2.0.0 and crashes on import. Use tagv1.1.3or newer (preferv1.1.4).Each IMAP tool call uses its own short-lived connection instead of one shared mailbox session
Inbox listings use header and snippet fetches instead of downloading full message bodies
Tool failures return clearer, agent-friendly error messages for bad UIDs, missing folders, and auth issues
Prompts such as
draft_replysend compact email payloads instead of full HTML blobsSent-folder archival no longer uses fragile
aioimaplibAPPEND. After every SMTP send, the server archives a CRLF-normalized copy intoSentwith stdlibimaplib, retries, and fails loudly if the Sent copy cannot be savedsend_draftrejects empty recipients or empty bodies before SMTPAttachment paths are validated as real files before send
Related MCP server: @aiwerk/mcp-server-imap
What it does
Reads inbox messages, threads, and attachments
Searches mail by sender, recipient, subject, body text, and date filters
Sends new emails
Replies and forwards while preserving thread headers
Saves and sends drafts
Moves, copies, deletes, and marks messages
Creates, renames, and deletes folders
Exposes inbox context as MCP resources
Exposes reusable prompts for summarizing inboxes and drafting replies
Saves sent messages into the
Sentfolder so they appear in PrivateEmail webmail
Why this exists
Namecheap PrivateEmail does not provide a public API for mailbox automation in the same way many SaaS products do. The supported integration path is standard email protocols. This server gives Claude Code a clean MCP interface on top of those protocols.
Features exposed to Claude Code
Tools
health_checkaccount_infolist_folderslist_emailssearch_emailsget_emailget_threaddownload_attachmentsend_emailreply_emailforward_emailsave_draftlist_draftssend_draftmove_emailcopy_emaildelete_emailmark_emailcreate_folderrename_folderdelete_folder
Resources
privateemail://accountprivateemail://foldersprivateemail://inbox/recentprivateemail://inbox/unreadprivateemail://email/{folder}/{uid}
Prompts
summarize_inboxtriage_unreaddraft_replycompose_email
Requirements
Python 3.11 or newer
uvinstalledA Namecheap PrivateEmail mailbox
Installation for Claude Code
Fastest install from GitHub
After this repository is pushed, add it directly to Claude Code with one command:
claude mcp add --scope user \
--env PRIVATEEMAIL_ADDRESS="you@yourdomain.com" \
--env PRIVATEEMAIL_PASSWORD="your-password" \
--env PRIVATEEMAIL_DISPLAY_NAME="Your Name" \
privateemail \
-- uvx --from git+https://github.com/ciphersolutions-dev/private-email-mcp privateemail-mcpNotes:
Install from tag
v1.1.3or newer (or currentmainafter that release). Older tags still have an unpinnedmcpdependency and will crash against MCP SDK 2.x.--scope userinstalls it once for all your projects. Use--scope projectif you want a repo-local setup instead.Everything after the
--separator is the command Claude Code runs.uvx --from git+... privateemail-mcpinstalls and launches the server directly from GitHub.
Install from a local clone
git clone https://github.com/ciphersolutions-dev/private-email-mcp.git
cd private-email-mcp
uv syncIf your network/VPN blocks outbound IMAP/SMTP (common), register the tunnel wrapper so Cursor starts the SSH LocalForward automatically:
# Cursor mcp.json command:
# /path/to/privateemail-mcp/scripts/run-mcp-with-tunnel.sh
# with env PRIVATEEMAIL_ADDRESS / PASSWORD / DISPLAY_NAME / PRIVATEEMAIL_TUNNEL_SSHDirect (no tunnel) when mail ports are reachable:
claude mcp add --scope user \
--env PRIVATEEMAIL_ADDRESS="you@yourdomain.com" \
--env PRIVATEEMAIL_PASSWORD="your-password" \
--env PRIVATEEMAIL_DISPLAY_NAME="Your Name" \
privateemail \
-- uv run --directory "$PWD" privateemail-mcpHelper install script
You can also use the included helper script after cloning the repo:
./scripts/install-claude-code.sh "you@yourdomain.com" "your-password" "Your Name"By default it registers the server at user scope. Pass a fourth argument of project to make it project scoped:
./scripts/install-claude-code.sh "you@yourdomain.com" "your-password" "Your Name" projectConfiguration
Environment variables:
PRIVATEEMAIL_ADDRESS- full mailbox addressPRIVATEEMAIL_PASSWORD- mailbox passwordPRIVATEEMAIL_DISPLAY_NAME- display name used for outbound mailPRIVATEEMAIL_IMAP_HOST- defaults tomail.privateemail.com(use127.0.0.1with the tunnel)PRIVATEEMAIL_IMAP_PORT- defaults to993(tunnel default21993)PRIVATEEMAIL_SMTP_HOST- defaults tomail.privateemail.com(use127.0.0.1with the tunnel)PRIVATEEMAIL_SMTP_PORT- defaults to465(tunnel default21465)PRIVATEEMAIL_TLS_HOSTNAME- TLS SNI/cert name when host is a tunnel loopback (default inferred asmail.privateemail.com)PRIVATEEMAIL_CONNECT_TIMEOUT- TCP connect timeout seconds (default12)PRIVATEEMAIL_COMMAND_TIMEOUT- IMAP/SMTP command timeout seconds (default30)PRIVATEEMAIL_TUNNEL_SSH- SSH host alias forscripts/mail-tunnel.sh(defaultubee)PRIVATEEMAIL_MAX_ATTACHMENT_BYTES- maximum attachment payload returned by the server
Example .env (tunnel mode):
PRIVATEEMAIL_ADDRESS=you@yourdomain.com
PRIVATEEMAIL_PASSWORD=your-password
PRIVATEEMAIL_DISPLAY_NAME=Your Name
PRIVATEEMAIL_IMAP_HOST=127.0.0.1
PRIVATEEMAIL_IMAP_PORT=21993
PRIVATEEMAIL_SMTP_HOST=127.0.0.1
PRIVATEEMAIL_SMTP_PORT=21465
PRIVATEEMAIL_TLS_HOSTNAME=mail.privateemail.com
PRIVATEEMAIL_TUNNEL_SSH=ubee
PRIVATEEMAIL_CONNECT_TIMEOUT=12
PRIVATEEMAIL_COMMAND_TIMEOUT=30
PRIVATEEMAIL_MAX_ATTACHMENT_BYTES=10485760Usage in Claude Code
Useful Claude Code commands:
claude mcp listclaude mcp get privateemailclaude mcp remove privateemail
Typical flows:
Read inbox: use
privateemail://inbox/recentor calllist_emailsReview unread mail: use
triage_unreadDraft a reply: use
draft_replySend a message now: use
send_emailReply in-thread: use
reply_emailSave a draft: use
save_draft
Development
uv sync
uv run pytest tests/ -qAcceptance tests are Gherkin features under features/, executed via pytest-bdd from tests/bdd/. They are the release gate for dependency compatibility, config/error contracts, Sent archival helpers, prompt payload safety, outbound guards, and MCP surface inventory.
Run locally:
uv run privateemail-mcpPrivateEmail behavior note
SMTP delivery alone does not create a copy in the Sent folder.
This server explicitly appends a copy to Sent after a successful send so the message shows up in PrivateEmail webmail.
Security
Keep your mailbox password in environment variables, not source control
.envis ignored by gitConsider using a dedicated mailbox or app-specific credential if your setup allows it
License
MIT
Available Tools
21 toolsaccount_infoARead-onlyIdempotent
Show configured mailbox address and server endpoints.
Inputs: no named parameters. Returns: result
copy_emailB
Copy an email to another folder.
Inputs: uid (required), dest_folder (required), folder. Returns: result
create_folderAIdempotent
Create an IMAP folder.
Inputs: name (required). Returns: result
delete_emailADestructiveIdempotent
Delete an email (moves to Trash unless expunge=True or already in Trash).
Inputs: uid (required), folder, expunge. Returns: result
delete_folderBDestructiveIdempotent
Delete an IMAP folder.
Inputs: name (required). Returns: result
download_attachmentARead-onlyIdempotent
Download an attachment by part_index from get_email.
Inputs: uid (required), part_index (required), folder, save_path. Returns: result
forward_emailB
Forward an email by UID to a new recipient.
Inputs: to (required), uid (required), note, folder. Returns: result
get_emailARead-onlyIdempotent
Fetch full email by UID including text/html and attachment metadata.
Inputs: uid (required), folder. Returns: result
get_threadBRead-onlyIdempotent
Fetch a conversation thread related to the given message UID.
Inputs: uid (required), limit, folder. Returns: result
health_checkARead-onlyIdempotent
Test IMAP and SMTP connectivity to mail.privateemail.com.
Inputs: no named parameters. Returns: result
list_draftsCRead-onlyIdempotent
List messages in the Drafts folder.
Inputs: limit. Returns: result
list_emailsBRead-onlyIdempotent
List recent email summaries in a folder.
Inputs: limit, since, folder, unread_only. Returns: result
list_foldersARead-onlyIdempotent
List IMAP folders in the PrivateEmail mailbox.
Inputs: no named parameters. Returns: result
mark_emailAIdempotent
Mark email read/unread and/or flagged/unflagged.
Inputs: uid (required), read, folder, flagged. Returns: result
move_emailB
Move an email to another folder.
Inputs: uid (required), dest_folder (required), folder. Returns: result
rename_folderA
Rename an IMAP folder.
Inputs: new_name (required), old_name (required). Returns: result
reply_emailA
Reply to an email by UID. Sets In-Reply-To and References for threading.
Inputs: uid (required), html, text, folder, +1 more. Returns: result
save_draftA
Save a draft into the Drafts IMAP folder.
Inputs: to (required), subject (required), cc, html, +1 more. Returns: result
search_emailsARead-onlyIdempotent
Search emails with IMAP criteria. Dates are YYYY-MM-DD.
Inputs: body, text, after, limit, +6 more. Returns: result
send_draftB
Send a draft by UID from Drafts, then move it to Trash.
Inputs: uid (required). Returns: result
send_emailA
Send an email via PrivateEmail SMTP. Prefer reply_email for threaded replies.
Inputs: to (required), subject (required), cc, bcc, +6 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Each tool targets a distinct operation: listing, searching, reading, sending, replying, forwarding, managing drafts, moving, copying, deleting, marking, and folder CRUD. No two tools appear to do the same thing, and descriptions clearly differentiate them.
All tools follow a consistent verb_noun pattern (e.g., list_emails, send_email, create_folder). The only slight deviation is health_check and account_info, but they still clearly convey their purpose and do not break the overall pattern.
21 tools is appropriate for an email server. It covers essential operations (read, send, reply, forward, manage drafts, move, copy, delete, mark, search) plus folder management and diagnostics, without being excessive.
The tool set covers the core email lifecycle: list, get, search, send, reply, forward, drafts, folder management. Minor gaps exist, such as no explicit tool to send an email with attachments or to list attachments independently, but these are possible through existing tools (send_email may support attachments, and get_email provides attachment metadata).
Maintenance
Related MCP Connectors
Hosted MCP server for your Gmail, Outlook and IMAP mail, with mailboxes and scopes set per agent.
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
A MCP server for Gmail that lets you search, read, and draft emails and replies.
MCP server for MailTempo's public free temporary email inboxes.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server for email operations supporting IMAP and SMTP protocols, enabling sending, receiving, searching, and managing emails with attachments.22 PyPI1MIT
- AlicenseBqualityCmaintenanceUniversal IMAP/SMTP MCP server that works with any email provider, providing tools to read, search, send, and manage emails.10242 npm1MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for managing email via IMAP/SMTP, supporting multiple accounts and tools for reading, sending, searching, and organizing emails.49 npmMIT
- AlicenseAqualityDmaintenanceMCP server that enables email management (send, read, search, delete, etc.) via IMAP/SMTP, compatible with Gmail, Outlook, Yahoo, iCloud, and other standard mail servers.11MIT