protonmail-mcp-server

A Model Context Protocol (MCP) server for Proton Mail — read-only email access through Proton Bridge.

Connect Claude (or any MCP client) to your Proton Mail so it can search, list, and read your email — without your email ever leaving your machine.

Features

• List folders with message and unread counts
• List emails with pagination, sorted newest first
• Search emails by sender, recipient, subject, body text, date range, read/flagged status
• Read full email content by IMAP UID, including attachment metadata
• Markdown and JSON response formats
• Input validation via Zod schemas
• Connection timeouts to prevent resource exhaustion

Prerequisites

• Node.js 18+
• Proton Bridge running on your machine with IMAP enabled
• Your Bridge-specific IMAP credentials (not your Proton account password)

Finding your Bridge credentials

1. Open Proton Bridge
2. Click your account name
3. Go to IMAP/SMTP settings (or Mailbox details)
4. Note the Username (your email) and Password (Bridge-generated)
5. Note the IMAP port (default: 1143)

Installation

npm install
npm run build

Or install globally from npm:

npm install -g protonmail-mcp-server

Configuration

Set these environment variables:

Variable	Required	Default	Description
PROTON_BRIDGE_USER	Yes	—	Bridge IMAP username (your email)
PROTON_BRIDGE_PASSWORD	Yes	—	Bridge-generated IMAP password
PROTON_BRIDGE_HOST	No	127.0.0.1	Bridge host
PROTON_BRIDGE_PORT	No	1143	Bridge IMAP port

Security: Configuration files containing your Bridge password are plaintext. Never commit them to version control or share them.

Adding to Claude Code

Add to your Claude Code MCP config (~/.claude/config.json or project-level):

{
  "mcpServers": {
    "protonmail": {
      "command": "node",
      "args": ["/path/to/protonmail-mcp-server/dist/index.js"],
      "env": {
        "PROTON_BRIDGE_USER": "your-email@proton.me",
        "PROTON_BRIDGE_PASSWORD": "your-bridge-password"
      }
    }
  }
}

Adding to Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "protonmail": {
      "command": "node",
      "args": ["/path/to/protonmail-mcp-server/dist/index.js"],
      "env": {
        "PROTON_BRIDGE_USER": "your-email@proton.me",
        "PROTON_BRIDGE_PASSWORD": "your-bridge-password"
      }
    }
  }
}

Available tools

proton_list_folders

List all mailbox folders with message and unread counts.

proton_list_emails

List emails in a folder (newest first) with pagination.

proton_get_email

Read a single email's full content by IMAP UID.

proton_search_emails

Search emails by sender, recipient, subject, body text, date range, read/flagged status.

Privacy & Security

• Read-only — all four tools are read-only; no email modification, deletion, or sending
• Localhost-only by default — connects to Proton Bridge on 127.0.0.1; TLS certificate validation is enforced for non-localhost connections
• No disk caching — opens a fresh IMAP connection per request, no email data is stored on disk
• No credential logging — your Bridge password is never logged, printed, or exposed in error messages
• Input validation — all inputs are validated with Zod schemas; folder names are sanitized against control characters
• Connection timeouts — all IMAP connections have configurable timeouts to prevent resource exhaustion

LLM Integration

This server implements the Model Context Protocol (MCP), making it compatible with any MCP client. When connected to an AI assistant like Claude, the assistant can:

• Check for new or unread emails
• Search for specific emails by sender, subject, or date
• Read and summarize email content
• Answer questions about your email (e.g., "What did Alice say about the quarterly report?")
• List your mailbox folders and their message counts

All operations are read-only — the assistant cannot send, delete, or modify your emails.

Development

npm run dev    # Watch mode with auto-reload
npm run build  # Production build
npm start      # Run built server

License

MIT