Proton Mail Bridge

  ____  ____   ___ _____ ___  _   _   __  __    _    ___ _
 |  _ \|  _ \ / _ \_   _/ _ \| \ | | |  \/  |  / \  |_ _| |
 | |_) | |_) | | | || || | | |  \| | | |\/| | / _ \  | || |
 |  __/|  _ <| |_| || || |_| | |\  | | |  | |/ ___ \ | || |___
 |_|   |_| \_\\___/ |_| \___/|_| \_| |_|  |_/_/   \_\___|_____|
  Bridge Client  ·  CLI + Claude Desktop MCP for Proton Mail

Give Claude Desktop (or Cline, or any MCP client) full access to your Proton Mail inbox: read, search, send, draft, triage threads, manage folders, save attachments, and more. The same 40+ capabilities are also available as a full CLI for scripting, cron, and piped automation — no Claude required.

What you get

• Claude reads and manages your Proton Mail — triage, reply, draft, archive, search, move, batch-act on threads, pull attachments
• Full CLI — same 40+ commands, scriptable and pipeable, works in cron and shell scripts
• Fast local search — full-text search across your inbox without hitting IMAP on every query
• Safety controls — read-only mode, send gate, destructive-action confirmation, per-action allowlist
• Privacy-native — no third-party email service involved; your mail stays on your machine

Privacy model

Your emails travel: Proton Mail → Proton Bridge (local) → this server (local) → your AI client.

Nothing goes through a third-party email relay. Proton Bridge decrypts your mail locally; this server reads it over a local IMAP connection on 127.0.0.1. The AI model (Claude Desktop, Cline, etc.) sees the email content you ask it to act on — that's the whole point — but no email leaves your machine except through your own Proton account when you send.

If you use Claude Desktop with the default Anthropic API, conversation content (including email snippets) is sent to Anthropic per their privacy policy. If you self-host an LLM or use a local-only Claude setup, nothing leaves your machine at all.

Prerequisites

1. Proton Bridge — must be installed, signed in, and running. Download: proton.me/mail/bridge

Bridge password vs Proton password: Proton Bridge generates a separate local password that is not your Proton account password. Find it inside the Bridge app under Account → Copy password (or similar — exact label varies by Bridge version). You'll need this for setup.

2. Node.js 18 or later — node --version to check.

3. Your Bridge credentials — from the Bridge app:

• IMAP host/port (default: 127.0.0.1:1143)
• SMTP host/port (default: 127.0.0.1:1025)
• Username (your Proton email address)
• Bridge password (see note above)

Install

npm (recommended):

npm install -g proton-mail-bridge-client

Homebrew:

brew tap googlarz/tap
brew install proton-mail-bridge-client

git clone https://github.com/googlarz/proton-mail-bridge-client.git
cd proton-mail-bridge-client
npm install
npm run build

Connect to Claude Desktop

Run the guided setup wizard:

proton-mail-bridge-client setup-claude-desktop

The wizard:

• checks your local Bridge ports
• asks for your Bridge username and Bridge password
• writes the Claude Desktop MCP config entry

After setup: restart Claude Desktop, make sure Proton Bridge is open, then check + → Connectors → proton-mail-bridge.

Updating

npm update -g proton-mail-bridge-client
proton-mail-bridge-client setup-claude-desktop

Manual config

The wizard handles config automatically. If you need to set it up by hand, three credential methods are supported:

{
  "mcpServers": {
    "proton-mail-bridge": {
      "command": "proton-mail-bridge-mcp",
      "env": {
        "PROTONMAIL_USERNAME": "[email protected]",
        "PROTONMAIL_PASSWORD": "your-bridge-password",
        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
        "PROTONMAIL_IMAP_PORT": "1143",
        "PROTONMAIL_IMAP_SECURE": "false",
        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
        "PROTONMAIL_SMTP_PORT": "1025"
      }
    }
  }
}

{
  "mcpServers": {
    "proton-mail-bridge": {
      "command": "proton-mail-bridge-mcp",
      "env": {
        "PROTONMAIL_USERNAME_FILE": "/path/to/username.txt",
        "PROTONMAIL_PASSWORD_FILE": "/path/to/password.txt",
        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
        "PROTONMAIL_IMAP_PORT": "1143",
        "PROTONMAIL_IMAP_SECURE": "false",
        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
        "PROTONMAIL_SMTP_PORT": "1025"
      }
    }
  }
}

{
  "mcpServers": {
    "proton-mail-bridge": {
      "command": "proton-mail-bridge-mcp",
      "env": {
        "PROTONMAIL_USERNAME_COMMAND": "pass proton/username",
        "PROTONMAIL_PASSWORD_COMMAND": "pass proton/password",
        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
        "PROTONMAIL_IMAP_PORT": "1143",
        "PROTONMAIL_IMAP_SECURE": "false",
        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
        "PROTONMAIL_SMTP_PORT": "1025"
      }
    }
  }
}

Connect to Cline (VS Code)

Install globally (npm install -g proton-mail-bridge-client), then open Cline's MCP settings:

• VS Code → Cline extension panel → MCP servers icon → Edit MCP Settings
• Or edit directly: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (macOS)

Add the server:

{
  "mcpServers": {
    "proton-mail-bridge": {
      "command": "proton-mail-bridge-mcp",
      "env": {
        "PROTONMAIL_USERNAME": "[email protected]",
        "PROTONMAIL_PASSWORD": "your-bridge-password",
        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
        "PROTONMAIL_IMAP_PORT": "1143",
        "PROTONMAIL_IMAP_SECURE": "false",
        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
        "PROTONMAIL_SMTP_PORT": "1025"
      }
    }
  }
}

For file-based or command-based credentials, use the same PROTONMAIL_USERNAME_FILE / PROTONMAIL_PASSWORD_COMMAND pattern from the Claude Desktop manual config above.

Reload the Cline extension after saving. Proton Mail tools will appear in Cline's tool list.

Try it: example Claude prompts

Morning triage

"Give me a digest of my inbox. Flag anything that needs a reply today and anything that looks like a bill or invoice."

Inbox zero

"Go through my unread emails from the past 3 days. Archive newsletters, trash anything promotional, and tell me what's left that needs action."

Folder filing

"Find all emails from stripe.com and move them to Folders/Receipts. Create the folder if it doesn't exist."

Meeting prep

"I have a call with [email protected] in an hour. Pull up our last 5 email threads and summarise the open items."

Draft review

"Show me my drafts, pick the oldest one, and suggest a better subject line and closing paragraph."

Tip: When creating folders, use Folders/Name (not just Name) — that's the Proton Bridge namespace for real folders vs. labels.

Recommended System Prompt

Add this to Claude Desktop's system prompt (Settings → Claude Desktop → System Prompt) for safer defaults:

You have access to my Proton Mail inbox via the proton-mail-bridge tool.

Rules:
- Always use dryRun: true before any batch operation (batch_email_action, apply_thread_action).
- Before calling send_email, reply_to_email, or forward_email, summarise what you are about to send and ask me to confirm.
- Before calling delete_email, confirm with me — deletion is permanent.
- Prefer create_draft over send_email when composing from scratch.
- Use get_inbox_digest or get_actionable_threads as your starting point for triage sessions.

CLI

proton-mail-bridge-client <command> [options]

All commands support --json for machine-readable output.

Read

proton-mail-bridge-client emails --folder INBOX --limit 25
proton-mail-bridge-client read INBOX::25642
proton-mail-bridge-client search "invoice" --limit 10
proton-mail-bridge-client search --live --from openai.com
proton-mail-bridge-client attachments INBOX::25642

Triage

proton-mail-bridge-client digest
proton-mail-bridge-client threads "quarterly review"
proton-mail-bridge-client actionable
proton-mail-bridge-client followups
proton-mail-bridge-client thread-brief <threadId>
proton-mail-bridge-client document-threads --category invoice
proton-mail-bridge-client meeting-context [email protected]

Compose & send

proton-mail-bridge-client send --to [email protected] --subject "Hey" --body "Hello"
echo "Hello" | proton-mail-bridge-client send --to [email protected] --subject "Hey"
proton-mail-bridge-client reply INBOX::25642 --body "On it."
proton-mail-bridge-client reply INBOX::25642 --reply-all --body "On it."
proton-mail-bridge-client forward INBOX::25642 --to [email protected]

Mailbox actions

proton-mail-bridge-client move INBOX::25642 Folders/Archive
proton-mail-bridge-client archive INBOX::25642
proton-mail-bridge-client trash INBOX::25642
proton-mail-bridge-client restore Trash::25642
proton-mail-bridge-client mark-read INBOX::25642
proton-mail-bridge-client mark-read INBOX::25642 --unread
proton-mail-bridge-client star INBOX::25642
proton-mail-bridge-client delete INBOX::25642
proton-mail-bridge-client batch archive INBOX::100,INBOX::101,INBOX::102
proton-mail-bridge-client thread-action <threadId> archive

Folders

proton-mail-bridge-client folders
proton-mail-bridge-client create-folder Folders/Receipts
proton-mail-bridge-client rename-folder Folders/Receipts Folders/Bills
proton-mail-bridge-client delete-folder Folders/Bills

Drafts

proton-mail-bridge-client drafts
proton-mail-bridge-client draft-create --to [email protected] --subject "Draft" --body "..."
proton-mail-bridge-client draft-read <id>
proton-mail-bridge-client draft-update <id> --subject "Updated subject"
proton-mail-bridge-client draft-reply INBOX::25642 --body "Will do."
proton-mail-bridge-client draft-forward INBOX::25642 --to [email protected]
proton-mail-bridge-client draft-sync <id>
proton-mail-bridge-client draft-send <id>
proton-mail-bridge-client draft-delete <id>
proton-mail-bridge-client remote-drafts

Analytics & diagnostics

proton-mail-bridge-client stats
proton-mail-bridge-client analytics
proton-mail-bridge-client contacts
proton-mail-bridge-client volume-trends --days 14
proton-mail-bridge-client watch --timeout 30
proton-mail-bridge-client test-email [email protected]
proton-mail-bridge-client doctor
proton-mail-bridge-client status
proton-mail-bridge-client sync --folder INBOX --limit 150

Ambient notifications

Run as a background daemon — sends a system notification (macOS / Linux) whenever new mail arrives:

proton-mail-bridge-client notify                              # foreground (Ctrl+C to stop)
proton-mail-bridge-client notify &                            # background
proton-mail-bridge-client notify --folder INBOX --timeout 60  # custom folder and idle timeout

Each event is also written as a JSON line to stdout:

{"event":"new_mail","folder":"INBOX","count":2,"at":"2026-05-18T14:32:01.000Z"}

Uses IMAP IDLE — no polling between events. Reconnects automatically on transient errors.

MCP tool passthrough

Any MCP tool is also callable directly from the CLI:

proton-mail-bridge-client tools
proton-mail-bridge-client tool get_connection_status --json
proton-mail-bridge-client tool search_indexed_emails --args '{"query":"invoice","limit":3}'

Pipe and script

# Morning digest to a file
proton-mail-bridge-client digest --json > ~/morning-mail.json

# Pull every email from a domain
proton-mail-bridge-client search --from stripe.com --json | jq '.[].subject'

# Pipe a script's output directly into an email
echo "Deploy complete on $(hostname) at $(date)" \
  | proton-mail-bridge-client send --to [email protected] --subject "Deploy done"

# Scheduled digest every weekday at 8am (cron)
0 8 * * 1-5 proton-mail-bridge-client digest >> ~/mail-log.txt

# Count unread in INBOX
proton-mail-bridge-client emails --folder INBOX --json | jq '[.[] | select(.isRead == false)] | length'

Safety controls

All flags work in both the MCP server and CLI:

PROTONMAIL_TOOL_TIER=core            # expose 20 core tools instead of all 76 — saves context window
PROTONMAIL_READ_ONLY=true            # disable all write operations
PROTONMAIL_ALLOW_SEND=false          # disable SMTP sends only (other writes still work)
PROTONMAIL_CONFIRM_DESTRUCTIVE=true  # require confirmed:true on send, reply, forward, delete
PROTONMAIL_ALLOWED_ACTIONS='mark_read,archive,trash'  # per-action allowlist

batch_email_action and apply_thread_action both support dryRun: true regardless of the above flags.

Environment reference

# Credentials (required)
PROTONMAIL_USERNAME='[email protected]'
PROTONMAIL_PASSWORD='your-bridge-password'   # Bridge password, not Proton account password
PROTONMAIL_IMAP_HOST='127.0.0.1'
PROTONMAIL_IMAP_PORT='1143'
PROTONMAIL_IMAP_SECURE='false'
PROTONMAIL_SMTP_HOST='127.0.0.1'
PROTONMAIL_SMTP_PORT='1025'

# Secrets via file or command (avoids raw credentials in config)
PROTONMAIL_USERNAME_FILE='/path/to/user.txt'
PROTONMAIL_PASSWORD_FILE='/path/to/pass.txt'
PROTONMAIL_USERNAME_COMMAND='pass proton/username'
PROTONMAIL_PASSWORD_COMMAND='pass proton/password'

# Storage
PROTONMAIL_DATA_DIR="$HOME/.proton-mail-bridge-client"

# Tools
PROTONMAIL_TOOL_TIER='full'          # 'core' exposes 20 essential tools (saves context window); 'full' exposes all 76

# Safety
PROTONMAIL_READ_ONLY='false'
PROTONMAIL_ALLOW_SEND='true'
PROTONMAIL_ALLOW_REMOTE_DRAFT_SYNC='true'
PROTONMAIL_ALLOWED_ACTIONS='mark_read,mark_unread,star,unstar,archive,trash,restore'
PROTONMAIL_CONFIRM_DESTRUCTIVE='false'

# Sync
PROTONMAIL_AUTO_SYNC='true'
PROTONMAIL_STARTUP_SYNC='true'
PROTONMAIL_SYNC_INTERVAL_MINUTES='5'
PROTONMAIL_IDLE_WATCH='true'
PROTONMAIL_IDLE_MAX_SECONDS='30'

Compared with Claude's native Gmail connector

Tool surface

Send

send_email · send_test_email · reply_to_email · reply_all_email · forward_email

Drafts

create_draft · create_reply_draft · create_forward_draft · create_thread_reply_draft · list_drafts · list_remote_drafts · get_draft · update_draft · sync_draft_to_remote · send_draft · delete_draft

Read

get_emails · get_email_by_id · count_messages · search_emails · search_indexed_emails · list_attachments · get_attachment_content · save_attachment · save_attachments

Triage

get_folders · sync_folders · get_labels · get_threads · get_thread_by_id · get_thread_brief · get_actionable_threads · get_inbox_digest · get_follow_up_candidates · find_document_threads · prepare_meeting_context · delete_thread · flag_thread · move_thread

Actions

mark_email_read · star_email · move_email · archive_email · trash_email · restore_email · delete_email · batch_email_action · apply_thread_action · empty_folder · bulk_delete · bulk_move · bulk_update_flags · bulk_update_labels · update_message_flags · update_message_labels

Folder management

create_folder · rename_folder · delete_folder · create_label

Analytics

get_email_stats · get_email_analytics · get_contacts · get_volume_trends · folder_stats · top_senders

Diagnostics

get_connection_status · get_runtime_status · run_doctor · get_audit_logs · run_background_sync · wait_for_mailbox_changes · sync_emails · get_index_status · clear_cache · clear_index · get_logs

Operational notes

• get_emails and search_emails return a composite emailId — use it for all subsequent reads and actions.
• search_indexed_emails supports from:, to:, subject:, label:, domain: shortcuts.
• The local index lives at PROTONMAIL_DATA_DIR/mail-index.sqlite. Background sync and IMAP IDLE keep it warm.
• Audit logs live at PROTONMAIL_DATA_DIR/audit.log.
• Draft sync is best-effort — the local draft is always preserved even if remote sync fails.
• System folders (INBOX, Sent, Trash, Spam, Archive, All Mail) are guarded against accidental deletion.

Troubleshooting

"Wrong password" or connection refused Make sure you're using the Bridge password, not your Proton account password. Find it in the Bridge app under Account → Copy password. Bridge must be running before the MCP server or CLI can connect.

macOS native module crash after update better-sqlite3 is a native binary built for your machine. After a major Node.js upgrade or environment change, rebuild it:

proton-mail-bridge-client setup-claude-desktop

This reinstalls the runtime and rebuilds native modules in place.

Claude can't see the connector After changing the MCP config, restart Claude Desktop fully (not just reload). Then check + → Connectors → proton-mail-bridge. If it's not there, run proton-mail-bridge-client doctor to validate the connection.

Folder not found when moving email Use Folders/Name for real folders (e.g., Folders/Receipts), not just Name. Labels and folders share the same namespace in Proton Bridge but are structurally different.

Changelog

See CHANGELOG.md for release history.

Contributing

Bug reports and pull requests welcome: github.com/googlarz/proton-mail-bridge-client/issues

License

MIT