baryon-mcp

# Baryon MCP

[![License](https://img.shields.io/github/license/combor/baryon-mcp)](LICENSE)
[![CI](https://github.com/combor/baryon-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/combor/baryon-mcp/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/combor/baryon-mcp)](https://github.com/combor/baryon-mcp/releases/latest)

## 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](https://proton.me/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:

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

Arch Linux — [`baryon-mcp-bin`](https://aur.archlinux.org/packages/baryon-mcp-bin) from the AUR:

```sh
yay -S baryon-mcp-bin
```

Debian-based Linux distributions (amd64 and arm64):

```sh
sudo apt install ./baryon-mcp_*.deb
```

RPM-based Linux distributions (amd64 and arm64):

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

Anywhere else, download the archive for your platform from the [latest release](https://github.com/combor/baryon-mcp/releases/latest) 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:

```sh
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

```sh
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:

```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`](https://protonpass.github.io/pass-cli/commands/contents/run/) can resolve it at launch, so the client configuration holds a reference instead of the password:

```sh
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](https://github.com/combor/baryon-mcp/releases/latest), 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:

```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 ou