protonmail-mcp

A small, local-first, read-only MCP server that lets ChatGPT search and read a Proton Mail account through Proton Mail Bridge.

The project intentionally does less than a normal email client. It cannot send, reply, delete, move, archive, label, mark read/unread, or download attachment bytes.

What ChatGPT gets

Four read-only tools:

• proton_health - verify Bridge connectivity without reading messages

• list_mailboxes - list folders/labels

• search_mail - search mail and return metadata plus optional short snippets

• get_message - fetch one decoded text message plus attachment metadata

Example prompts after connecting the app:

Search my Proton inbox for mail from Proton about security keys.

Find emails with "Daybreak Blue" from the last 30 days and summarize the important ones.

Read the message with the subject "Interview details" and tell me the date and action items.

Related MCP server: ProtonScope

Why Proton Mail Bridge

Proton Mail Bridge decrypts Proton Mail locally and exposes IMAP to local email clients. This server connects only to that local IMAP interface. Use the Bridge-generated IMAP password, never your Proton Account password.

Requirements

• A Proton plan that includes Proton Mail Bridge

• Proton Mail Bridge installed and signed in

• Python 3.10+

• uv recommended, or ordinary pip

• ChatGPT Developer Mode plus a way to expose the local MCP through OpenAI Secure MCP Tunnel

Install

Unzip the project, then:

cd protonmail-mcp
cp .env.example .env
chmod 600 .env
$EDITOR .env
uv sync --extra dev
uv run protonmail-mcp doctor

Fill .env from Proton Mail Bridge -> Mailbox details. Port and security mode can vary, so use what Bridge actually shows.

Start the server:

uv run protonmail-mcp serve

Default endpoint:

http://127.0.0.1:8765/mcp

See docs/CHATGPT_SETUP.md for the ChatGPT connection steps.

pip alternative

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
protonmail-mcp doctor
protonmail-mcp serve

Search API

search_mail accepts:

• query: IMAP text search across headers/body

• sender: sender filter

• subject: subject filter

• after: inclusive ISO date, for example 2026-09-01

• before: exclusive ISO date

• mailbox: exact mailbox name, or omit to search All Mail when available

• limit: capped locally, default 20

• include_snippet: return a short text preview, default true

Search results include an opaque ref. Pass that ref to get_message.

Read-only guarantees in this codebase

This is not only a prompt-level promise.

1. There is no SMTP implementation or dependency.

2. Every SELECT call uses readonly=True.

3. Every body fetch uses BODY.PEEK.

4. There is no code path calling IMAP STORE, COPY, MOVE, APPEND, or EXPUNGE.

5. MCP tools declare the standard read-only annotation.

6. The MCP HTTP listener refuses non-loopback hosts.

7. The Bridge IMAP target refuses non-loopback hosts unless you explicitly opt in.

You can audit these claims with:

rg -n 'STORE|COPY|MOVE|APPEND|EXPUNGE|SMTP|BODY\\[' src tests

BODY[ should appear only in tests that verify the parser's fake IMAP response. Production fetch queries use BODY.PEEK.

TLS note

Proton Mail Bridge normally uses a locally generated self-signed TLS certificate. This project therefore defaults to certificate verification off only for the loopback Bridge connection. Non-loopback IMAP is blocked by default, and if explicitly enabled it requires TLS verification.

Prompt-injection note

Email is attacker-controlled input. A malicious message can contain text such as "ignore your instructions". The server converts HTML to inert text, never loads remote content, and marks mail as untrusted external data in tool responses. The model still needs to treat message content as data rather than instructions.

Tests

uv run pytest
uv run ruff check .

The tests include a contract check that searches use read-only mailbox selection and BODY.PEEK.

Current limitations

• No attachment body retrieval, only metadata.

• No conversation/thread reconstruction yet.

• Search uses IMAP semantics, so advanced Proton web-search syntax is not implemented.

• Very large messages are withheld above PROTON_MCP_MAX_MESSAGE_BYTES instead of pulling large attachments into model context.

• ChatGPT custom MCP apps currently require ChatGPT web according to OpenAI's help documentation.

License

MIT