Installing Proton Bridge MCP.

Before you start

You need Proton Mail Bridge installed, signed in, and running. Bridge is a paid feature, so a free Proton account can't use this. Open Bridge and find Mailbox details, that's where the hostname, ports, username and password come from. Bridge picks its own port numbers, they aren't always 1143 and 1025, so read them rather than assuming.

You won't need to install Python first if you follow the uv route, it fetches its own. Going the plain-Python route instead, you'll want Python 3.9 or newer. Either way, two small packages go into a local virtual environment, so they don't touch anything else on your system: pypdf reads the text out of PDFs, and keyring stores your password in the credential store on Linux and Windows. macOS has its own Keychain command built in, so keyring is optional there, but installing it does no harm.

Install

It goes on this computer, the same machine as Bridge and your assistant. A cloud AI session won't do, because its commands run in a sandbox on someone else's machine, where Bridge isn't, and nothing ends up installed here.

Clone it somewhere permanent, a folder in your home directory is right. Your assistant's config will point at this exact path, and the settings, audit log and saved attachments live next to the server, so a folder that later moves is a connection that breaks. Not Downloads, not a temp folder, not anywhere a cloud drive syncs.

Both routes finish the same way. setup.py opens a small page in your browser, served from your own machine on a random port behind a single-use link. It shuts itself down when you're finished and it never logs anything you type. Copy the values across from Bridge, and it'll test both connections before it saves a thing. Your password goes into your computer's secure credential store, never into a file.

Run it again any time. It notices you've set it up before, fills in what it already knows, and a blank password field means keep the one you've got.

Have an assistant do it

Paste this into an AI assistant that runs shell commands on this computer, Claude Code or a desktop assistant with terminal access, not a chat on a website, whose commands run on a server far from your Bridge. Read what it proposes before you let it run.

Please install the Proton Bridge MCP server from https://github.com/Considus/proton-bridge-mcp
on this computer, following the Install section of its README exactly. Clone it into a permanent
folder in my home directory, create the virtual environment with pypdf and keyring installed,
then run setup.py using that environment's own Python, and tell me the local link it prints so
I can finish setup in my browser. Run the commands one at a time, not chained together, and show
me each one before you run it.

Or run the commands yourself

In its own terminal, that's Terminal on macOS, PowerShell on Windows.

You'll need git and uv, both free. Macs and most Linux machines have git already; Windows has neither, and winget install Git.Git followed by winget install astral-sh.uv in PowerShell puts that right, then open a fresh PowerShell window so they're found.

macOS and Linux

git clone https://github.com/Considus/proton-bridge-mcp.git

cd proton-bridge-mcp

uv venv .venv --python 3.12

uv pip install --python .venv/bin/python pypdf keyring

.venv/bin/python setup.py

Windows (PowerShell)

git clone https://github.com/Considus/proton-bridge-mcp.git

cd proton-bridge-mcp

uv venv .venv --python 3.12

uv pip install --python .venv\Scripts\python.exe pypdf keyring

.venv\Scripts\python.exe setup.py

Run each line on its own rather than chaining them together. The stock Windows PowerShell doesn't understand && between commands, and a line that half-works is harder to unpick than five that ran one at a time.

That last line matters. Setup runs with the environment you just built, which is where keyring went, and that's how your password reaches the credential store on Windows and Linux. The system's own Python doesn't have it and can't save the password there.

No uv? Use plain Python, 3.9 or newer. On macOS and Linux that's python3 -m venv .venv then .venv/bin/python -m pip install pypdf keyring. On Windows it's python -m venv .venv then .venv\Scripts\python -m pip install pypdf keyring. Then run setup with the environment's Python exactly as shown. Drop pypdf and you lose PDF text extraction. Drop keyring and you lose saved-password storage on Linux and Windows.

Connect it to your assistant

When setup finishes it hands you a second prompt. Paste that into whichever assistant you want reading your mail, Claude, Cursor, Windsurf, Zed, Codex CLI, Gemini CLI, VS Code Copilot, whatever you're using.

It works this way round on purpose. Every client keeps its MCP config somewhere different, under a different key, and those locations move. An assistant already knows where its own config lives, so asking it beats shipping a list of paths that quietly rots. The prompt carries no password and no settings, only the name, the command and the path.

Restart the app afterwards, MCP servers load at startup.

Where things live

Passwords sit in your operating system's credential store, Keychain, Credential Manager or Secret Service depending on what you're running. Everything else goes in settings.json next to the server, owner-readable only, no secrets in it. Environment variables override the file if you'd rather configure it that way, and .env.example covers the ones most people need. The rest are named where they come up in this README.

Using it writes three more files, all next to the server and all owner-readable only. state.json keeps polling cursors and rate counters, audit.log records everything that changed something, and saved attachments land in attachments/ until the TTL sweeps them. Each one has an override, PROTON_STATE_FILE, PROTON_AUDIT_LOG and PROTON_ATTACH_DIR, so none of them are stuck where they land by default.

audit.log is the one worth a thought about where it sits. It keeps recipient addresses, subject lines and folder names in the clear, message bodies never, so over time it accumulates a record of who you write to without ever becoming a second copy of your mail. It rotates at 5MB and nothing expires by age, so the record runs as far back as your last 5MB of activity. That makes the folder you cloned into a question rather than a given. If it gets backed up, synced or indexed, the metadata goes with it, and pointing PROTON_AUDIT_LOG at somewhere outside that tree keeps the record on the machine that made it. On macOS a directory under ~/Library/Application Support/ that you exclude from Time Machine does the job, and excluding the directory rather than the file matters, because the rotated audit.log.1 is a new file that needs to inherit the exclusion.

Tests

On macOS and Linux:

.venv/bin/python -m unittest discover -s tests -v

On Windows:

.venv\Scripts\python.exe -m unittest discover -s tests -v

They cover attachment classification, the write sandbox, the recipient rules and the MCP protocol itself. None of them need Bridge running or a real account.

Support

This is free and stays that way. Apache 2.0 means you can take it, build on it, and ship it commercially without owing anything back, which is deliberate.

If it saved you an afternoon, there's buymeacoffee.com/considus. If it didn't, opening an issue when something breaks is worth more than the coffee.

Licence

Apache 2.0. See LICENSE for the terms and NOTICE for the attribution you need to carry with it. The bundled fonts are licensed separately under the SIL Open Font License 1.1, in assets/fonts/OFL.txt.