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

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

### Local and self-hosted AI

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

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

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

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