Skip to main content
Glama
PrivateEmail MCP

PrivateEmail MCP

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 993 and SMTP 465. Direct connects then hang until the client times out. Use scripts/run-mcp-with-tunnel.sh (SSH LocalForward via a host that can reach mail.privateemail.com, default ubee). The wrapper starts the tunnel and points IMAP/SMTP at 127.0.0.1:21993 / 127.0.0.1:21465 with PRIVATEEMAIL_TLS_HOSTNAME=mail.privateemail.com.

  • Fail-fast timeouts: PRIVATEEMAIL_CONNECT_TIMEOUT (default 12s) and PRIVATEEMAIL_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 tag v1.1.3 or newer (prefer v1.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_reply send compact email payloads instead of full HTML blobs

  • Sent-folder archival no longer uses fragile aioimaplib APPEND. After every SMTP send, the server archives a CRLF-normalized copy into Sent with stdlib imaplib, retries, and fails loudly if the Sent copy cannot be saved

  • send_draft rejects empty recipients or empty bodies before SMTP

  • Attachment 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 Sent folder 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_check

  • account_info

  • list_folders

  • list_emails

  • search_emails

  • get_email

  • get_thread

  • download_attachment

  • send_email

  • reply_email

  • forward_email

  • save_draft

  • list_drafts

  • send_draft

  • move_email

  • copy_email

  • delete_email

  • mark_email

  • create_folder

  • rename_folder

  • delete_folder

Resources

  • privateemail://account

  • privateemail://folders

  • privateemail://inbox/recent

  • privateemail://inbox/unread

  • privateemail://email/{folder}/{uid}

Prompts

  • summarize_inbox

  • triage_unread

  • draft_reply

  • compose_email

Requirements

  • Python 3.11 or newer

  • uv installed

  • A 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-mcp

Notes:

  • Install from tag v1.1.3 or newer (or current main after that release). Older tags still have an unpinned mcp dependency and will crash against MCP SDK 2.x.

  • --scope user installs it once for all your projects. Use --scope project if you want a repo-local setup instead.

  • Everything after the -- separator is the command Claude Code runs.

  • uvx --from git+... privateemail-mcp installs 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 sync

If 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_SSH

Direct (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-mcp

Helper 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" project

Configuration

Environment variables:

  • PRIVATEEMAIL_ADDRESS - full mailbox address

  • PRIVATEEMAIL_PASSWORD - mailbox password

  • PRIVATEEMAIL_DISPLAY_NAME - display name used for outbound mail

  • PRIVATEEMAIL_IMAP_HOST - defaults to mail.privateemail.com (use 127.0.0.1 with the tunnel)

  • PRIVATEEMAIL_IMAP_PORT - defaults to 993 (tunnel default 21993)

  • PRIVATEEMAIL_SMTP_HOST - defaults to mail.privateemail.com (use 127.0.0.1 with the tunnel)

  • PRIVATEEMAIL_SMTP_PORT - defaults to 465 (tunnel default 21465)

  • PRIVATEEMAIL_TLS_HOSTNAME - TLS SNI/cert name when host is a tunnel loopback (default inferred as mail.privateemail.com)

  • PRIVATEEMAIL_CONNECT_TIMEOUT - TCP connect timeout seconds (default 12)

  • PRIVATEEMAIL_COMMAND_TIMEOUT - IMAP/SMTP command timeout seconds (default 30)

  • PRIVATEEMAIL_TUNNEL_SSH - SSH host alias for scripts/mail-tunnel.sh (default ubee)

  • 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=10485760

Usage in Claude Code

Useful Claude Code commands:

  • claude mcp list

  • claude mcp get privateemail

  • claude mcp remove privateemail

Typical flows:

  • Read inbox: use privateemail://inbox/recent or call list_emails

  • Review unread mail: use triage_unread

  • Draft a reply: use draft_reply

  • Send a message now: use send_email

  • Reply in-thread: use reply_email

  • Save a draft: use save_draft

Development

uv sync
uv run pytest tests/ -q

Acceptance 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-mcp

PrivateEmail 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

  • .env is ignored by git

  • Consider using a dedicated mailbox or app-specific credential if your setup allows it

License

MIT

Available Tools

21 tools
account_infoA
Read-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_folderA
Idempotent

Create an IMAP folder.

Inputs: name (required). Returns: result

delete_emailA
DestructiveIdempotent

Delete an email (moves to Trash unless expunge=True or already in Trash).

Inputs: uid (required), folder, expunge. Returns: result

delete_folderB
DestructiveIdempotent

Delete an IMAP folder.

Inputs: name (required). Returns: result

download_attachmentA
Read-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_emailA
Read-onlyIdempotent

Fetch full email by UID including text/html and attachment metadata.

Inputs: uid (required), folder. Returns: result

get_threadB
Read-onlyIdempotent

Fetch a conversation thread related to the given message UID.

Inputs: uid (required), limit, folder. Returns: result

health_checkA
Read-onlyIdempotent

Test IMAP and SMTP connectivity to mail.privateemail.com.

Inputs: no named parameters. Returns: result

list_draftsC
Read-onlyIdempotent

List messages in the Drafts folder.

Inputs: limit. Returns: result

list_emailsB
Read-onlyIdempotent

List recent email summaries in a folder.

Inputs: limit, since, folder, unread_only. Returns: result

list_foldersA
Read-onlyIdempotent

List IMAP folders in the PrivateEmail mailbox.

Inputs: no named parameters. Returns: result

mark_emailA
Idempotent

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_emailsA
Read-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

    A3.7/5.0

    Scored across 21 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for email operations supporting IMAP and SMTP protocols, enabling sending, receiving, searching, and managing emails with attachments.
      22 PyPI
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Universal IMAP/SMTP MCP server that works with any email provider, providing tools to read, search, send, and manage emails.
      10
      242 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for managing email via IMAP/SMTP, supporting multiple accounts and tools for reading, sending, searching, and organizing emails.
      49 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that enables email management (send, read, search, delete, etc.) via IMAP/SMTP, compatible with Gmail, Outlook, Yahoo, iCloud, and other standard mail servers.
      11
      MIT