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 < 1.25.0, set MCP_SSE_KEEPALIVE=false to avoid JSON parsing errors. 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:

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