Proton Bridge MCP

Proton Bridge MCP

Give any AI assistant read, organise and carefully-gated send access to your Proton Mail, without handing your mail to anyone.

Proton is end-to-end encrypted, which is the whole point of it, and it's also why there's no API to plug an assistant into. Your mail is only readable on your own machine. Proton Mail Bridge is the piece that decrypts locally and speaks ordinary IMAP and SMTP to 127.0.0.1, so with Bridge in place this server never has to send your mail anywhere at all.

Unofficial, and not affiliated with or endorsed by Proton AG.

Docs · Install · Security · FAQ

What it can do

Search and read mail, pull attachments out and read them (including the text of PDF invoices), tag and file messages one at a time or in batches, reply in thread, and send or forward behind a confirmation step.

Anything that sends takes draft=true instead, which puts it in your Drafts for you to look at. That path needs no confirmation, because nothing goes anywhere.

Files can be attached to anything you send, though only from directories you've said are allowed. Reading any file on the machine and posting it out is how data walks off a computer, so the default is the attachments folder and widening it is your decision, not something an instruction in an email can talk it into.

Three things it can't do, and won't pretend otherwise. Folders can be created and renamed but not deleted, because a folder is where a message actually lives and deleting one would have to decide what happens to the mail inside it, so that stays a job for the Proton app. Bridge has no access to Proton's server-side filters or auto-forwarding rules, so those stay a manual job in the Proton web app. And nothing here hard-deletes, the furthest it goes is Trash.

Watching for new mail

poll_folder hands back whatever has turned up since you last looked, which is what turns this from something that reads your mail when asked into something that can react to mail arriving.

The first poll on a folder returns nothing on purpose. It notes where the folder currently ends, so switching it on doesn't dump years of backlog into a conversation. It reads nothing as read either.

If you're doing something with each message that you'd rather not do twice, poll with advance=false. You get the batch and a checkpoint, the cursor stays where it was, and polling again hands you the same batch until you confirm, by polling once more with the checkpoint as commit. Crash halfway and you pick up where you left off instead of losing the lot. Confirming twice is harmless.

The cursor records the UIDVALIDITY next to the message number, so a folder that resyncs underneath you is spotted rather than acted on. When that happens it re-anchors to the current end and says so, because the alternative is replaying whatever those old numbers now point at.

Getting at attachments

Three situations, two tools. read_attachment pulls the text out and is what you want almost always, invoices included, and nothing touches the disk. save_attachment writes the file out for anything that isn't text, and works if whatever you're using can read files off disk. And read_attachment hands an image straight back so it can be looked at, which is the only route to a photo or a scan when the client can't reach the filesystem.

Images only for that last one, on purpose. Encoding a file to send it inline makes it a third bigger and drops it into the conversation as characters, and for a spreadsheet or a Word document that's a lot of context spent on something nothing can read. Images are different because they arrive as an image rather than as text, so they cost about what a picture costs and can actually be seen.

Searching everywhere

A message in Proton lives in one folder but also turns up under every label you've put on it, and again in All Mail. Sweep the lot naively and you get the same mail three times. search_mail across every folder matches on Message-ID, arrival time and size instead, so you get one entry per message with the other places it appears listed underneath, and it scans All Mail last as a safety net rather than treating it as a source. Every hit carries the UIDVALIDITY of the folder it was found in, because those differ per folder and a uid without one isn't safe to act on.

UIDs go stale

IMAP identifies a message by a number that's only meaningful until the folder resyncs. When that happens the number quietly starts pointing at something else, which is how the wrong message gets filed or trashed. Every folder reports a UIDVALIDITY alongside its uids, and if you hand one back with a uid that no longer matches, the tool refuses and asks you to search again rather than acting on the wrong mail.

Conversations aren't messages

Worth knowing before you trust an answer about attachments. Proton's app groups mail into conversations and shows a paperclip if anything in the thread has one. IMAP hands over individual messages with no grouping at all. A reply sitting in your inbox can be completely empty while the original, filed somewhere else, is carrying the PDFs. That's why find_thread exists, and why "no attachments" from a single message is an answer worth checking.

Things to actually ask it

Four that exercise different parts of it, and none of them need you to know a tool name.

"Find the invoices from my accountant this quarter and total them up." Searches, then opens the attachments and reads the text out of the PDFs. This is the one that justifies bundling a PDF library rather than telling you an invoice exists and leaving you to open it.

"What's arrived since I last checked, and what actually needs me?" Uses the checkpointed batch, so if it falls over halfway you get the same batch again rather than losing it. Poll with advance=false and nothing moves until you say so.

"File everything from Companies House into Admin, but show me the list first." A search, then a bulk move. The preview runs every check the real thing would, and the move needs confirming on top of it, because moving 50 messages somewhere you didn't intend is an afternoon.

"Draft a reply to Sam saying I'll confirm Monday. Don't send it." Goes to your Drafts and stops. That path needs no confirmation at all, because nothing has gone anywhere.

Other mail providers

Bridge is what this was built for, and it's the case with no alternative, since Proton has no API to point anything else at. The rest of it is ordinary IMAP and SMTP though, so it works against a normal mailbox too, which is useful if your business mail comes from a smaller host rather than Google or Microsoft.

Labels are the one place the two differ. Proton keeps them in their own namespace, so Marketing and Labels/Marketing both work and mean the same thing. An ordinary IMAP server has no such idea, so a label there is just another folder and tagging copies the message into it. The server works out which kind it's talking to rather than assuming, and if the name matches nothing it tells you what does exist.

Set the hostname and ports to whatever your provider gave you. There's no autodiscovery here. Nothing guesses the server name from your email domain, and there's no lookup of the usual mail. records, so you enter the exact values from your provider's IMAP/SMTP settings page, for example mail.lcn.com with its IMAP and SMTP ports. Once you've typed the name your operating system resolves it to an address the normal way. What isn't automated is working out *which* name to use. Security is worked out from the port, 993 and 465 mean TLS from the first byte, 143 and 587 mean it gets negotiated, and you can say which explicitly if your host is unusual. Plain unencrypted connections aren't offered, since sending your password in clear isn't a trade worth making.

Go in with your eyes open on one thing. Every guarantee in Security still holds except the first one, because your mail now lives on a server you don't control and travels over the internet to get here. That's a fair trade if the alternative is no assistant access at all, it just isn't the same promise.

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 liv