@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

Variable	Required	Default	Description
PROTONMAIL_USERNAME	Yes	—	Your ProtonMail email address
PROTONMAIL_PASSWORD	Yes	—	Proton Bridge app password
SMTP_HOST	No	127.0.0.1	Bridge SMTP host
SMTP_PORT	No	1025	Bridge SMTP port
IMAP_HOST	No	127.0.0.1	Bridge IMAP host
IMAP_PORT	No	1143	Bridge IMAP port
DEBUG	No	false	Enable debug logging

Tools

Tool	Description
sendEmail	Send an email with optional CC, BCC, HTML body, attachments, and priority
replyEmail	Reply to an existing email by UID
listFolders	List all mailboxes and folders
listEmails	List emails with pagination (page-based or stable cursor via beforeUid)
readEmail	Read email by UID (supports headersOnly and maxBodyLength for efficiency)
searchEmails	Search by sender, subject, body, date range, read/flagged status (with cursor pagination)
bulkAction	Bulk delete, move, mark read/unread, flag/unflag by criteria or UIDs (dry run by default)
markRead	Mark an email as read
markUnread	Mark an email as unread
flagEmail	Star/flag an email
unflagEmail	Remove star/flag from an email
moveEmail	Move an email to another folder
deleteEmail	Move an email to Trash
createFolder	Create a new mail folder
deleteFolder	Delete a mail folder
renameFolder	Rename a mail folder
createLabel	Create a new mail label
deleteLabel	Delete a mail label
renameLabel	Rename a mail label
connectionStatus	Check SMTP and IMAP connection health

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