Protonmail Mcp Server

ProtonMail MCP Server

Unofficial IMAP-backed MCP (Model Context Protocol) server for ProtonMail Bridge. Exposes mailbox operations as MCP tools so AI assistants can list, search, and retrieve mail through a local Bridge connection.

News

v2026.2.2 - Breaking Change

search_emails renamed to get_inbox_items - The old search_emails tool (which listed emails with optional date filtering) has been renamed to get_inbox_items to better reflect its purpose.

New search_emails with keyword search - A new search_emails tool now provides actual keyword-based searching with field selection:

{
  "mailbox": "INBOX",
  "query": "meeting notes",
  "fields": ["subject", "from"],
  "since_date": "2025-01-01T00:00:00Z",
  "limit": 30
}

| Parameter | Required | Description | |-----------|----------|-------------| | query | Yes | Search keywords | | fields | No | Fields to search: text (anywhere), subject, from, to, body. Defaults to text. | | since_date | No | ISO 8601 date filter | | mailbox | No | Defaults to INBOX | | limit | No | Defaults to 30 |

Quickstart

Install

Prebuilt binaries (recommended):

Linux:

curl -LO https://github.com/TensorTemplar/protonmail-mcp-server/releases/latest/download/protonmail-mcp-server-x86_64-unknown-linux-gnu.tar.gz
tar xzf protonmail-mcp-server-x86_64-unknown-linux-gnu.tar.gz
chmod +x protonmail-mcp-server
sudo mv protonmail-mcp-server /usr/local/bin/

macOS (Apple Silicon):

curl -LO https://github.com/TensorTemplar/protonmail-mcp-server/releases/latest/download/protonmail-mcp-server-aarch64-apple-darwin.tar.gz
tar xzf protonmail-mcp-server-aarch64-apple-darwin.tar.gz
chmod +x protonmail-mcp-server
sudo mv protonmail-mcp-server /usr/local/bin/

macOS (Intel):

curl -LO https://github.com/TensorTemplar/protonmail-mcp-server/releases/latest/download/protonmail-mcp-server-x86_64-apple-darwin.tar.gz
tar xzf protonmail-mcp-server-x86_64-apple-darwin.tar.gz
chmod +x protonmail-mcp-server
sudo mv protonmail-mcp-server /usr/local/bin/

Windows (PowerShell):

Invoke-WebRequest -Uri "https://github.com/TensorTemplar/protonmail-mcp-server/releases/latest/download/protonmail-mcp-server.exe-x86_64-pc-windows-msvc.zip" -OutFile "protonmail-mcp-server.zip"
Expand-Archive protonmail-mcp-server.zip -DestinationPath .

Via cargo:

# From crates.io
cargo install protonmail-mcp-server --features http

# Or from source
git clone https://github.com/TensorTemplar/protonmail-mcp-server
cd protonmail-mcp-server
cargo install --path . --features http

Verify Downloads (Optional)

All release binaries include SHA256 checksums signed with Sigstore.

Checksum verification:

# Download the checksums file
curl -LO https://github.com/TensorTemplar/protonmail-mcp-server/releases/latest/download/SHA256SUMS.txt

# Verify your downloaded binary (run in same directory as the .tar.gz/.zip)
sha256sum -c SHA256SUMS.txt --ignore-missing
# Expected output: protonmail-mcp-server-x86_64-unknown-linux-gnu.tar.gz: OK

Signature verification (requires cosign):

# Download the signature bundle
curl -LO https://github.com/TensorTemplar/protonmail-mcp-server/releases/latest/download/SHA256SUMS.txt.bundle

# Verify the checksums file was signed by this repo's GitHub Actions
cosign verify-blob \
  --certificate-identity-regexp "github.com/TensorTemplar/protonmail-mcp-server" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --bundle SHA256SUMS.txt.bundle \
  SHA256SUMS.txt
# Expected output: Verified OK

Configure and Run

# Set environment variables
export IMAP_HOST=127.0.0.1
export IMAP_PORT=1143
export IMAP_USERNAME=your@email.com
export IMAP_PASSWORD=your-bridge-password
export MCP_TRANSPORT=http
export MCP_AUTH_TOKEN=your-secret-token

# Run
protonmail-mcp-server

Or copy and edit the example env file:

cp .env.example .env
# Edit .env with your settings
protonmail-mcp-server

HTTP Transport Deployment

Architecture

┌─────────────┐     HTTPS/SSE      ┌──────────────────┐     IMAP
│   Agent 1   │◄──────────────────►│                  │◄──────────►┌────────────────┐
├─────────────┤                    │   MCP Server     │            │ ProtonMail     │
│   Agent 2   │◄──────────────────►│   (HTTP+SSE)     │◄──────────►│ Bridge         │
├─────────────┤                    │                  │            │                │
│   Agent N   │◄──────────────────►│ Per-session IMAP │◄──────────►│ localhost:1143 │
└─────────────┘                    └──────────────────┘            └────────────────┘

• Each MCP session gets its own IMAP connection
• Bearer token authentication required
• SSE (Server-Sent Events) for streaming responses

Configuration

| Variable | Default | Description | |----------|---------|-------------| | MCP_TRANSPORT | stdio | Transport mode: stdio or http | | MCP_HTTP_BIND | 127.0.0.1:8080 | HTTP server bind address | | MCP_AUTH_TOKEN | (required for http) | Bearer token for authentication | | MCP_SSE_KEEPALIVE | true | Enable SSE keep-alive pings (see note below) |

> Note: If using Python MCP SDK The older SDK can't handle empty SSE data fields sent as keep-alive pings. > See: python-sdk#1672

Running HTTP Server

# Via environment
MCP_TRANSPORT=http MCP_AUTH_TOKEN=secret123 ./target/release/protonmail-mcp-server

# Via CLI override
./target/release/protonmail-mcp-server --transport http --bind 0.0.0.0:8080

Client Usage

# Initialize session
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer secret123" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

Security Considerations

1. Network binding: Default 127.0.0.1 (localhost only). Use 0.0.0.0 for remote access.
2. Authentication: MCP_AUTH_TOKEN is mandatory for HTTP mode.
3. TLS: For production, deploy behind a reverse proxy (nginx, Caddy) with HTTPS.

Available MCP Tools

| Tool | Description | Annotations | |------|-------------|-------------| | list_mailboxes | List available mailboxes | read-only | | get_inbox_items | Get emails from a mailbox with optional date filtering | read-only | | search_emails | Search emails by keyword in specified fields | read-only | | get_email | Fetch full email content by ID | read-only | | get_current_date | Get current UTC timestamp | read-only | | list_tags | List available flags for a mailbox | read-only | | get_email_tags | Get flags on a specific email | read-only | | apply_tag | Apply a flag to an email | idempotent | | remove_tag | Remove a flag from an email | destructive | | move_email | Move email to another folder | destructive | | move_emails | Move multiple emails to another folder | destructive | | get_attachment | Download attachment (file or base64) | destructive, open-world |

Sponsors

If you find this project useful, consider supporting us:

[](https://buy.stripe.com/28o4gL5Qu9URaFaeUU) [](https://buy.stripe.com/aEUaF992G5EBaFa8wx)

Please include your name and project in the payment notes to be listed in SPONSORS.md.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TensorTemplar
• Source: TensorTemplar/protonmail-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.