protonmail-mcp-server

# protonmail-mcp-server A Model Context Protocol (MCP) server for Proton Mail — read-only email access through Proton Bridge. [](LICENSE) [](https://nodejs.org/) 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 ```bash npm install npm run build ``` Or install globally from npm: ```bash 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): ```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" } } } } ``` ## Adding to Claude Desktop Add to `claude_desktop_config.json`: ```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](https://modelcontextprotocol.io/) (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 ```bash npm run dev # Watch mode with auto-reload npm run build # Production build npm start # Run built server ``` ## License [MIT](LICENSE)