@darkroomhq/protonmail-mcp

MCP server that gives AI assistants full access to your ProtonMail account via Proton Bridge. Read, send, search, and manage email through any MCP-compatible client.

Requirements

• Proton Bridge running locally and signed in

• Node.js 18+

Installation

npm install -g @darkroomhq/protonmail-mcp

Or use without installing:

npx @darkroomhq/protonmail-mcp

Configuration

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "protonmail": {
      "command": "protonmail-mcp",
      "env": {
        "PROTONMAIL_USERNAME": "your@protonmail.com",
        "PROTONMAIL_PASSWORD": "bridge-app-password"
      }
    }
  }
}

With npx (no global install needed):

{
  "mcpServers": {
    "protonmail": {
      "command": "npx",
      "args": ["-y", "@darkroomhq/protonmail-mcp"],
      "env": {
        "PROTONMAIL_USERNAME": "your@protonmail.com",
        "PROTONMAIL_PASSWORD": "bridge-app-password"
      }
    }
  }
}

Note: PROTONMAIL_PASSWORD is the Bridge app password shown in Proton Bridge, not your ProtonMail account password.

All environment variables

Tools

Example prompts

Read & summarize

• "Summarize my unread emails from this week."

• "Read the latest email from alice and tell me what she's asking for."

Search

• "Find all emails about the Q2 report from the last 30 days."

• "Search for any flagged emails in my Sent folder."

Send & reply

• "Send an email to bob letting him know the meeting is moved to Thursday at 3pm."

• "Reply to the last email from the design team and ask for the updated mockups."

Bulk operations

• "Delete all emails from IGN in my inbox."

• "Mark all unread newsletters as read."

• "Move all emails from noreply@github.com to the GitHub folder."

• "How many flagged emails do I have from the last month?" (uses dry run)

Organize

• "Move all newsletters from my inbox to the Newsletters folder."

• "Flag the three most recent emails from my manager."

• "Delete all emails in the Spam folder."

• "Create a folder called 'Receipts' and move all purchase confirmations there."

• "Create a label called 'Urgent' for emails that need immediate attention."

• "Rename the 'Old Projects' folder to 'Archive'."

Status

• "Check if Proton Bridge is connected."

Performance tips

• Cursor pagination: Use beforeUid (returned as nextCursor) instead of page for stable pagination that isn't affected by new emails arriving between requests.

• Headers only: Use headersOnly: true on readEmail to skip downloading the full message body — useful when you only need metadata.

• Body truncation: Use maxBodyLength on readEmail to cap body size (e.g. 2000 chars) and avoid large responses from email-heavy messages.

• Bulk actions: Use bulkAction with search criteria instead of looping over individual emails. It runs a single IMAP SEARCH + a single bulk command, regardless of how many emails match.

• Dry run: bulkAction defaults to dryRun: true — preview affected emails before committing destructive operations.

Development

npm install
npm run build   # compile TypeScript
npm run dev     # watch mode