Baryon MCP

A local, permission-limited bridge between Proton Mail and the AI you choose

Baryon connects an MCP-compatible AI assistant to Proton Mail through a local Proton Mail Bridge.

It lets your assistant search and read email, understand conversations, work with attachments, and prepare drafts for you to review. Baryon cannot send email, move or delete ordinary messages, or mark messages as read.

Baryon has no hosted service. You decide which MCP client and AI model receive your email content.

[!IMPORTANT] Baryon and Proton Mail Bridge run locally, but your AI may not.

Email content requested through Baryon is returned to your MCP client and can be passed to the model it uses. With a local or self-hosted model, processing can remain on infrastructure you control, depending on your client configuration. With a hosted service, selected email content is sent to that provider.

For example, using Baryon with hosted Claude or Codex models sends requested email content to Anthropic or OpenAI infrastructure respectively. Review your client's and provider's privacy and data-retention terms before connecting it to your mailbox.

What you can do

Find messages by text, sender, recipient, subject, date, or unread state.
Read an email or an entire conversation.
Inspect, retrieve, and save attachments.
Prepare new messages as Proton Mail drafts.
Review, edit, and send those drafts yourself in Proton Mail.

For example, you could ask your assistant:

Find the renewal notices I received this month and summarise the price changes.

Read my conversation with Alice and prepare a polite follow-up draft.

Find the PDF invoice attached to the latest message from Acme and save it locally.

Summarise this support thread and draft a reply covering the unresolved questions.

Useful access, deliberate limits

Capability	Available
Search and read email	Yes
Read complete conversations	Yes
List and retrieve attachments	Yes
Save attachments locally	Yes, on macOS and Linux
Create and replace drafts	Yes
Save a derived reply draft	Yes
Restrict reading to chosen folders	Optional
Send email	No
Move ordinary messages	No
Delete ordinary messages	No
Mark messages as read or change flags	No

Replacing an existing draft saves its replacement before removing the previous draft copy. Baryon has no tool for deleting ordinary received or sent messages.

How it works

text

Proton Mail
    │
    ▼
Proton Mail Bridge       local
    │
    ▼
Baryon                   local
    │
    ▼
Your MCP client
    │
    ├── Local model      can stay on infrastructure you control
    │
    └── Hosted model     content is sent to its provider

Baryon talks only to Proton Mail Bridge on your computer. It refuses to send Bridge credentials to a non-loopback address and verifies Bridge using its exported TLS certificate by default.

Before you start

You will need:

Proton Mail Bridge installed, signed in, and running.
An MCP client that can launch local MCP servers over stdio.
The IMAP username and generated password shown in Bridge's mailbox settings.
Bridge's exported TLS certificate for a verified connection.

Use the password generated by Bridge, not your normal Proton account password. Export cert.pem from Settings → Advanced settings → Export TLS certificates in Proton Mail Bridge.

Installation

1. Install the binary

macOS:

brew install --cask combor/tap/baryon-mcp

Windows (after the generated manifest is accepted into the WinGet Community Repository):

powershell

winget install --exact --id Combor.BaryonMCP

Arch Linux — baryon-mcp-bin from the AUR:

yay -S baryon-mcp-bin

Debian-based Linux distributions (amd64 and arm64):

sudo apt install ./baryon-mcp_*.deb

RPM-based Linux distributions (amd64 and arm64):

sudo rpm --install ./baryon-mcp_*.rpm

Anywhere else, download the archive for your platform from the latest release and extract baryon-mcp onto your PATH. Releases provide macOS, Linux, FreeBSD, and OpenBSD builds for amd64 and arm64, Windows amd64 builds, and DEB and RPM packages for Linux amd64 and arm64, alongside a SHA256SUMS file. Hash your download and compare it with the matching line in that file:

sha256sum baryon-mcp_*.tar.gz            # Linux archive
sha256sum baryon-mcp_*.deb               # Linux DEB
sha256sum baryon-mcp_*.rpm               # Linux RPM
shasum -a 256 baryon-mcp_*.tar.gz        # macOS
sha256 baryon-mcp_*.tar.gz               # FreeBSD and OpenBSD

powershell

Get-FileHash baryon-mcp_*.zip -Algorithm SHA256   # Windows

2. Run the setup

baryon-mcp setup

Setup pins Bridge's TLS certificate, stores your Bridge credentials, and registers baryon with any installed Claude Code and Codex CLIs, which then launch the binary directly — no wrapper script and no credentials in a client configuration file. The Bridge password goes into the system keyring (Secret Service on Linux with gnome-keyring, KWallet or KeePassXC running; Login Keychain on macOS; Credential Manager on Windows), and into a mode-600 file under ~/.config/baryon-mcp when no keyring answers.

On Linux, if no exported certificate is found, setup offers to pin the certificate the running Bridge is serving — after verifying through procfs that the process owning the port is a Bridge executable running as you — and shows its fingerprint before asking. Bridge installed headlessly (protonmail-bridge-core) has no certificate-export UI, so this is the expected path there. baryon-mcp setup --help lists the options, including --reset-credentials, --tls-cert and --client.

Configuring a client by hand

baryon-mcp setup knows how to configure Claude Code and Codex. For any other MCP client, point it at the baryon-mcp binary yourself. The surrounding configuration format varies between clients, but the server entry looks like this:

config.json

{
  "mcpServers": {
    "baryon": {
      "command": "/absolute/path/to/baryon-mcp",
      "env": {
        "PROTON_BRIDGE_USERNAME": "you@proton.me",
        "PROTON_BRIDGE_PASSWORD": "bridge-generated-password",
        "PROTON_BRIDGE_TLS_CERT": "/absolute/path/to/cert.pem"
      }
    }
  }
}

This basic configuration may store Bridge credentials as plaintext. Prefer baryon-mcp setup, which keeps them out of client configuration entirely, or your client's secure secret storage. Any variable set here takes precedence over the stored credentials, so the two can be mixed — a client entry can override the endpoint while the password stays in the keyring.

Proton Pass CLI

If you keep the Bridge password in Proton Pass, pass-cli run can resolve it at launch, so the client configuration holds a reference instead of the password:

Terminal

claude mcp add --transport stdio --scope user baryon \
  -e PROTON_BRIDGE_USERNAME=you@proton.me \
  -e "PROTON_BRIDGE_PASSWORD=pass://Personal/Proton Bridge/password" \
  -- pass-cli run --no-masking -- /usr/bin/baryon-mcp

pass-cli run passes the MCP stdio stream through unchanged and preserves the exit code. --no-masking matters: by default pass-cli rewrites any occurrence of the resolved secret in the child's output, which would corrupt a tool result whose mailbox content happens to contain the Bridge password. An expired Proton Pass session or an unresolvable reference fails on stderr before the server starts, which surfaces in the client's MCP log.

Hosted AI clients

[!CAUTION] The installation methods below connect Baryon to hosted AI products. Email content retrieved through Baryon is sent to the relevant provider when the client gives it to the model.

Claude Desktop

Download the .mcpb bundle for your platform from the latest release, open it, and enter the Bridge settings when prompted.

Claude Code and Codex

Install the binary and run baryon-mcp setup, as above. It registers both CLIs it finds on PATH; --client claude or --client codex configures only one, and an existing baryon entry is left alone unless --force-client-config is given.

Docker on Linux

ghcr.io/combor/baryon-mcp is published for linux/amd64 and linux/arm64. It exists so MCP directories can start the server and read its tool schemas, and so Linux users can run Baryon in a container. On macOS and Windows use the native binaries: Docker Desktop does not share the host loopback interface that Bridge listens on.

Baryon speaks stdio, so the client launches the container rather than connecting to a port:

config.json

{
  "mcpServers": {
    "baryon": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network=host",
        "--user", "1000:1000",
        "--env-file", "/absolute/path/to/baryon.env",
        "-v", "/absolute/path/to/cert.pem:/run/secrets/bridge-cert.pem:ro",
        "-v", "/absolute/path/to/attachments:/attachments",
        "-e", "PROTON_BRIDGE_TLS_CERT=/run/secrets/bridge-cert.pem",
        "-e", "BARYON_ATTACHMENT_ROOTS=/attachments",
        "ghcr.io/combor/baryon-mcp:latest"
      ]
    }
  }
}

--network=host is required. Bridge listens on the host's loopback interface, and Baryon refuses to send credentials to any other address.
Keep PROTON_BRIDGE_USERNAME and PROTON_BRIDGE_PASSWORD in the env file and supply them at run time. It holds the Bridge password in plain text, so create it outside any repository and chmod 600 it. Never bake credentials into an image or commit them in a Compose file.
Replace 1000:1000 with your own id -u and id -g. Bind mounts keep host ownership, so without --user the container runs as UID 65532 and cannot read a mode-0600 certificate or write into your attachment directory. save_attachment creates files mode 0600 owned by whichever UID the container ran as, so running as yourself keeps them readable.
Keep BARYON_ATTACHMENT_ROOTS pointed at the mounted directory, as above. Without it the server creates its attachment directory under the container user's home, which a --user override usually cannot write to, and startup fails rather than falling back to unrestricted access.
Anyone who can reach the Docker daemon can read a running container's environment. On a desktop, prefer a native binary configured with baryon-mcp setup, which keeps credentials in the system keyring or in mode-600 files.
With both credentials absent the image still starts and serves tool schemas, so a directory can inspect it; every tool call then reports the missing configuration. Supplying only one credential fails at startup.

Security boundaries

Baryon refuses to send Bridge credentials to a non-loopback host.
Bridge's TLS certificate is pinned by default. Without a certificate, Baryon refuses to start unless insecure mode is explicitly enabled.
Read tools select mailboxes read-only and do not mark messages as read.
save_draft and save_reply_draft are the only tools that change the mailbox, and only inside Drafts. There are no send, move, general delete, or flag-changing tools.
save_attachment is the only tool that writes to local disk. It never overwrites an existing file or creates a missing parent directory.
Local attachment reads and writes are confined to a managed folder by default, or to the directories chosen with BARYON_ATTACHMENT_ROOTS.
Reading can be limited to an allowlist of folders with BARYON_ALLOWED_FOLDERS. A folder outside it is refused before the mailbox is opened, and never appears in list_folders.
Replies can only be sent from the addresses in BARYON_SENDER_IDENTITIES, and never carry the original message's Bcc recipients.
Message content is labelled content_trust: "untrusted_email" wherever it is returned, and fenced with an unguessable delimiter for clients that read only text blocks.
MCP clients can access the message content and attachments you request. Connect only clients and models you trust.

Advanced reference

Available MCP tools

Tool	Description
`list_folders`	List the mailbox folders this server may read
`list_emails`	List messages in a folder, newest first, with cursor pagination
`search_emails`	Search by text, sender, recipient, subject, date, or unread state
`get_email`	Read metadata, Sender/Reply-To/Bcc addresses, plain-text/HTML bodies, and attachment metadata
`get_thread`	Read a whole conversation from one of its messages, oldest first, optionally with shortened bodies
`list_attachments`	List attachment metadata without downloading content
`get_attachment`	Fetch one attachment into the conversation, up to 25 MB decoded
`save_attachment`	Write one attachment to a local file and return only its path
`list_sender_identities`	List the addresses a draft may be sent from
`save_draft`	Create or replace a draft with text, HTML, Bcc recipients, and attachments from base64 or local file paths
`save_reply_draft`	Save a reply to one message as a new draft, deriving recipients, subject and threading headers

Configuration options

Environment variable	Default	Description
`PROTON_BRIDGE_USERNAME`	—	Required Bridge IMAP username
`PROTON_BRIDGE_PASSWORD`	—	Required Bridge-generated password
`PROTON_BRIDGE_HOST`	`127.0.0.1`	Bridge host; loopback addresses only
`PROTON_BRIDGE_IMAP_PORT`	`1143`	Bridge IMAP port
`PROTON_BRIDGE_IMAP_SECURITY`	`starttls`	`starttls` or `tls`
`PROTON_BRIDGE_TLS_CERT`	auto-detect	Path to Bridge's exported certificate
`PROTON_BRIDGE_ALLOW_INSECURE`	`false`	Disable certificate verification; see the warning below
`BARYON_ATTACHMENT_ROOTS`	`${XDG_CONFIG_HOME:-~/.config}/baryon-mcp/attachments`	Path-list-separated directories that `save_draft` may read from and `save_attachment` may write to
`BARYON_SENDER_IDENTITIES`	the Bridge username	Comma-separated RFC 5322 addresses a draft may be sent from; the first is the default
`BARYON_ALLOWED_FOLDERS`	every folder	One CSV row of folder names the reading tools are limited to; quote a name containing a comma
`BARYON_ALLOW_UNCONFIGURED_INTROSPECTION`	`false`	Serve tool schemas with no credentials at all; set by the container image

Baryon creates the default attachment directory at mode 0700 when it starts, and refuses to start if it cannot. Setting BARYON_ATTACHMENT_ROOTS replaces that default entirely — those directories must already exist. On Windows there is no attachment directory, because both file-touching tools refuse to run there.

BARYON_ALLOWED_FOLDERS names must match Bridge's spelling exactly, except INBOX, which matches case-insensitively. Draft saving is outside this scope, so a reply can still be saved when Drafts is not on the list.

Without an explicit or auto-discovered certificate, Baryon refuses to start unless PROTON_BRIDGE_ALLOW_INSECURE=true. Insecure mode allows another local process to impersonate Bridge and capture its generated password.

BARYON_ALLOW_UNCONFIGURED_INTROSPECTION=true applies only when both credentials are absent, which is how a published image can be started and inspected without a mailbox. Every tool call then fails with a configuration error, and a half-configured server — one credential set, the other missing — still refuses to start.

Stored credentials and `baryon-mcp setup`

baryon-mcp setup stores credentials that the server loads whenever the corresponding environment variable is unset; a set environment variable always wins. The layout under ${XDG_CONFIG_HOME:-~/.config}/baryon-mcp (mode 0700):

Item	Location
Bridge username	`bridge-username`, mode-600 file
Bridge password	Secret Service keyring when available, otherwise `bridge-password`, mode-600 file
Bridge certificate	`cert.pem`, mode-600 file

The keyring item is stored under service baryon-mcp-proton-bridge with the Bridge address as its username, so a keyring browser shows it as Password for 'you@proton.me' on 'baryon-mcp-proton-bridge' and

secret-tool lookup service baryon-mcp-proton-bridge username you@proton.me

retrieves it. Exactly one password store survives a setup run: saving into the keyring removes the file, and falling back to the file removes the keyring item. A keyring that stops answering — or blocks locked for more than ten seconds — reads as "no stored credentials" rather than an error, so containers and headless machines keep working.

Reading messages and attachments

For reading mail:

Call list_folders.
Call list_emails or search_emails.
Pass the returned folder, uid, and uidvalidity to get_email or the attachment tools.

Every summary carries the message's message_id, which correlates the same message across folders — the copy in All Mail and the copy in INBOX share it, while their UIDs do not.

For the next page, pass the returned next_before_uid back as before_uid, together with uidvalidity. Mail arriving between two calls then cannot shift or repeat a result, which plain offset paging cannot promise. offset still works, but the two cannot be combined, and the call fails rather than paging a mailbox whose uidvalidity changed.

Attachments come back in two ways. get_attachment returns the bytes inline—images as image content and other files as base64—which puts them in the conversation. save_attachment writes the decoded bytes to a path and returns only the path, so a large attachment never reaches the model's context.

output_path may be relative, in which case it resolves inside the attachment directory, or absolute and inside it. The parent directory must already exist and the target file must not. Both attachment tools are bounded at 25 MB decoded, so save_attachment removes the context cost, not the fetch cap.

Replying

save_reply_draft answers one message. Pass the folder, uid and uidvalidity you read it with, plus the body; everything else is derived from the message:

Recipients come from its Reply-To, else its From, else its Sender. Your own addresses are removed and duplicates collapse. A message that names nobody else there — one of your own, or one forging your address — is refused rather than answered at the other recipients it lists; save_draft is where you name recipients yourself.
reply_all additionally copies its To and Cc. The original Bcc is never carried over; only a bcc you pass yourself is kept.
from must be one of BARYON_SENDER_IDENTITIES — call list_sender_identities to see them. Omitted, Baryon picks the identity the message was addressed to, then the one it was sent from, then the default.
Subject keeps an existing Re: prefix, in any case, or gains one.
Threading sets In-Reply-To to the parent's Message-ID and References to its chain followed by it. A message with no Message-ID is refused: it cannot be threaded correctly, and save_draft remains available for it.

The original body is not quoted and its attachments are not copied — pass whatever the reply should contain. The response echoes every derived field, so the recipients can be reviewed before you send the draft from Proton Mail. save_reply_draft only ever creates a draft; replacing one stays with save_draft.

Creating and replacing drafts

For drafts, omit uid and uidvalidity to create one. To replace an existing draft, pass both values and submit the complete desired state. Read the current draft with get_email and fetch any attachments first so recipients, bodies, and files can be retained.

Each attachment supplies its content in exactly one of two ways:

content_base64: inline bytes, with filename and content_type required.
content_path: a path to a regular file on the machine running Baryon, relative to the attachment directory or absolute and inside it. filename defaults to the path's basename and content_type is inferred from the extension.

All attachments are read and validated before anything touches the mailbox, so a missing or unreadable file fails the call without creating or replacing a draft.

save_reply_draft derives a reply's threading for you. To thread one by hand, read the message being answered with get_email, then pass its message_id as in_reply_to, and its references followed by that same message_id as references. When the parent reports no references, use its in_reply_to in their place, as RFC 5322 section 3.6.4 prescribes.

Angle brackets are optional on message identifiers, but each identifier must be a well-formed id-left@id-right. Baryon rejects anything it could not read back and strips the self-reference Bridge adds to References, so the chain it reports can be quoted as-is.

A replacement gets a new UID. Baryon appends it before removing the previous draft and returns a warning if cleanup is incomplete. The replacement keeps the previous draft's Message-ID, plus whichever of its In-Reply-To and References the call omits. Omitting one of those fields keeps the existing header; passing an empty array removes it and detaches the draft from its thread.

Limits and platform notes

Draft limits:

50,000 characters each for plain-text and HTML bodies.
100 regular attachments.
100 message identifiers each in in_reply_to and references, with 512 bytes per identifier. A longer chain read from a message is trimmed to its most recent identifiers.
25 MB decoded per attachment and in total, across both content sources.
Generated RFC822/MIME message below 70 MiB.
Standard base64 for inline content; inline CID attachments are not supported.
content_path and save_attachment are not available on Windows. Use content_base64 and get_attachment there.

Baryon speaks MCP 2026-07-28 and negotiates down to any earlier revision back to 2024-11-05, so older clients keep working.

Detailed local-file protections

The draft tools with content_path read local files with the server's privileges. They refuse anything but regular files after resolving symlinks. save_attachment never overwrites and creates no directories. Every read tool, including get_attachment, is annotated read-only.

Both are confined to the same directories. Unset, that is the managed ${XDG_CONFIG_HOME:-~/.config}/baryon-mcp/attachments, created at mode 0700 when the server starts; BARYON_ATTACHMENT_ROOTS replaces it with directories of your own, which must already exist. A relative path resolves inside the first of them, and an absolute path must fall inside one — a path escaping the boundary is refused rather than followed.

Attachment roots are pinned by identity when the server starts. Replacing a root afterwards—renaming it and leaving a symlink in its place, for example—does not move the boundary. If every root becomes unreachable, both tools refuse all paths rather than falling back to unrestricted access.

Upgrading from a release before the managed directory: with BARYON_ATTACHMENT_ROOTS unset, content_path and output_path used to accept any absolute path the server's account could reach. They are now confined to the managed directory. To keep using other locations, set BARYON_ATTACHMENT_ROOTS explicitly; the Docker example above already does, so container users are unaffected.

Development

Building from source requires Go 1.26.5 or later.

make build      # build ./baryon-mcp
make test       # formatting, shell script checks, vet, and race-enabled tests
make snapshot   # local GoReleaser build and MCPB packaging into dist/

make snapshot also requires GoReleaser, jq, and npx.

License

BSD 3-Clause