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.

When something goes wrong

The connection is refused. Bridge isn't running, or it isn't on the ports this is looking at. Bridge picks its own port numbers per install and they aren't always 1143 and 1025, so open it, read the real ones out of Mailbox details, and set PROTON_IMAP_PORT and PROTON_SMTP_PORT to match.

The login is rejected. This is the common one by a distance. Bridge has a password of its own, shown in Bridge under Mailbox details, and it isn't your Proton account password. The account password is refused every time, and what you get back looks like a broken install rather than the wrong credential.

It says setup is required. Run python3 setup.py and let it walk you through. Doing it by hand instead, set PROTON_USER to the address Bridge shows you, then supply the Bridge password either through the PROTON_BRIDGE_PASSWORD environment variable or through your computer's credential store.

A uid that worked ten minutes ago is refused. The folder resynced underneath you and those numbers now point at different mail, so the refusal is the tool doing its job rather than failing at it, described in UIDs go stale. Search again and act on the uid the search hands back, not the one you were holding.

An attachment you can see in Proton isn't there. Proton's app groups mail into conversations, IMAP hands over individual messages, and the reply sitting in your inbox can be completely empty while the original, filed somewhere else, carries the PDFs. find_thread is the way round it, and Conversations aren't messages is why.

It stopped and asked you before sending. Working as designed, not a fault. Nothing leaves the machine without you saying so, which is Nothing goes out quietly.

Updating

There's no package and no installer, so there's nothing to download. The server runs as server.py out of the directory you cloned into, which makes an update a pull and a restart.

The restart is the part that catches people out. A stdio MCP server is a long-running process, and it reads server.py once, when the app starts it. Changing the file underneath a server that's already running does nothing at all, so quit the app properly and open it again. Closing the window isn't enough on macOS, and neither is closing the last tab on Windows if it leaves the app in the tray.

Releases are tagged, and the releases page on GitHub says what changed in each one and whether it affects you. Plenty of what lands here only matters on a mailbox that isn't Proton, so a release you can safely ignore is a normal outcome rather than a sign something went wrong. git pull puts you on the latest main, which is sometimes ahead of the newest tag.

Have an assistant do it

Paste this into an AI assistant that runs shell commands on this computer. It can do the pull, but it can't restart the app it's running inside, so the last step stays yours.

Please update my Proton Bridge MCP server. Find where it's installed by reading the path out
of this app's MCP config rather than guessing it, run git pull in that folder, and tell me what
changed and which release that puts me on. Don't edit any of my settings or touch settings.json,
state.json or audit.log. Then remind me to quit this app completely and open it again, because
the server only reads server.py at startup.

Or run the commands yourself

In the folder you cloned into.

cd proton-bridge-mcp

git pull

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.

Something broken or behaving oddly, open an issue. Anything exploitable goes through GitHub's private reporting instead, described in SECURITY.md, not a public issue. For anything that doesn't fit either, including press and licensing, it's <support@considus.com>, and the rest of the ways to reach us are at considus.com/support.

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.