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 and replies 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
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

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

Local and self-hosted AI

Download and extract the archive for your platform from the latest release. Releases provide macOS and Linux builds for amd64 and arm64, and a Windows amd64 build.

Point your MCP client at the extracted baryon-mcp binary. The surrounding configuration format varies between clients, but the server entry looks like this:

{
  "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. Use your client's secure secret storage when available.

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

The installers download the latest platform archive, verify its SHA-256 checksum, install a credential-backed launcher, and configure installed Claude Code and Codex CLIs.

macOS or Linux:

(
  set -e
  installer=$(mktemp "${TMPDIR:-/tmp}/baryon-install.XXXXXX")
  trap 'rm -f "$installer"' EXIT
  curl -fsSL https://raw.githubusercontent.com/combor/baryon-mcp/main/scripts/install.sh -o "$installer"
  sh "$installer"
)

Windows PowerShell:

$installer = Join-Path ([IO.Path]::GetTempPath()) ("baryon-install-{0}.ps1" -f [Guid]::NewGuid().ToString("N"))
try {
  Invoke-WebRequest -UseBasicParsing -Uri https://raw.githubusercontent.com/combor/baryon-mcp/main/scripts/install.ps1 -OutFile $installer
  powershell.exe -NoProfile -ExecutionPolicy Bypass -File $installer
} finally {
  Remove-Item -Force $installer
}

Use --client claude or --client codex on macOS/Linux, or -Client claude / -Client codex on Windows, to configure only one client. Existing baryon entries are preserved unless --force-client-config or -ForceClientConfig is supplied.

The installers protect Bridge credentials as follows:

• macOS: Login Keychain service baryon-mcp; the launcher contains no secrets.
• Linux: separate mode-600 files under $XDG_CONFIG_HOME/baryon-mcp (default ~/.config/baryon-mcp).
• Windows: current-user DPAPI encryption under %LOCALAPPDATA%\baryon-mcp.

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 is the only tool that changes the mailbox. 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 can be restricted to directories chosen with BARYON_ATTACHMENT_ROOTS.
• MCP clients can access the message content and attachments you request. Connect only clients and models you trust.

Advanced reference

<details> <summary>Available MCP tools</summary>

Tool	Description
list_folders	List mailbox folders
list_emails	List messages in a folder, newest first, with pagination
search_emails	Search by text, sender, recipient, subject, date, or unread state
get_email	Read metadata, Bcc recipients, 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
save_draft	Create or replace a draft with text, HTML, Bcc recipients, and attachments from base64 or local file paths

</details>

<details> <summary>Configuration options</summary>

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	unrestricted	Path-list-separated directories that save_draft may read from and save_attachment may write to

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.

</details>

<details> <summary>Reading messages and attachments</summary>

For reading mail:

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

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 takes an absolute output_path, writes the decoded bytes there, and returns only the path, so a large attachment never reaches the model's context.

For save_attachment, the parent directory must already exist and the target file must not exist. When BARYON_ATTACHMENT_ROOTS is set, the path must fall inside an allowed directory. Both attachment tools are bounded at 25 MB decoded, so save_attachment removes the context cost, not the fetch cap.

</details>

<details> <summary>Creating and replacing drafts</summary>

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: an absolute path to a regular file on the machine running Baryon. 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.

To reply inside a thread, read the message being answered with get_email. 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.

</details>

<details> <summary>Limits and platform notes</summary>

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.

</details>

<details> <summary>Detailed local-file protections</summary>

save_draft with content_path reads local files with the server's privileges. It refuses anything but regular files after resolving symlinks. BARYON_ATTACHMENT_ROOTS optionally restricts which directories it may read; unset means any file your user account can read.

save_attachment never overwrites, creates no directories, and is confined by the same BARYON_ATTACHMENT_ROOTS. Unset means any path your user account can write. Every other read tool, including get_attachment, is annotated read-only.

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

</details>

Development

Building from source requires Go 1.26.5 or later.

make build      # build ./baryon-mcp
make test       # formatting, installer 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