# proton-mail-mcp

> Unofficial MCP server for Proton Mail Bridge. It lets an AI assistant search and read mail, write drafts and tidy a mailbox, with a preview the user approves before mail is moved, deleted or sent. It runs on the user's own computer and listens only on 127.0.0.1. Not affiliated with or endorsed by Proton AG.

An assistant connected to the server gets its instructions from the server itself, when it connects and in the tool list. These pages are for reading about the project, helping someone set it up, or explaining a result.

The package is `mcp-proton-mail` on PyPI: `uvx mcp-proton-mail setup --client <client>` installs it, as the README does. An agent setting it up for someone follows llms-install.md: it uses `--json`, which lists what only the person can do, and hands the person the Bridge login.

## Start here

- [README](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/README.md): What the server does, its safety model and the install with `uvx mcp-proton-mail setup`
- [Getting started](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/getting-started.md): A first session, from install to approving and undoing a change
- [Documentation map](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/README.md): Every page, by what you need

## Set up

- [Install](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/install.md): The installer in full, its --json output for agents, manual install, launchd, Tailscale Serve, uninstall
- [Install with an AI agent](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/llms-install.md): Steps for an agent installing the server for someone, with the human login hand-off
- [Connect an MCP client](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/clients.md): The connect command, configure-client and --print-config, safe config merges, generic MCP over HTTP
- [Claude Desktop](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/clients/claude-desktop.md): The connect entry, the .mcpb bundle, MCP Apps views
- [Claude Code](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/clients/claude-code.md): claude mcp add at user scope, a project's own entry, and the plugin
- [ChatGPT Mac app](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/clients/chatgpt.md): Direct HTTP in ~/.codex/config.toml, with the token
- [Codex](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/clients/codex.md): codex mcp add, or the config.toml table
- [Gemini CLI](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/clients/gemini.md): gemini mcp add at user scope, or settings.json
- [Cursor](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/clients/cursor.md): The mcp.json entry and one-click install links
- [Grok Bot and other agents](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/clients/grok-bot.md): The connector entry an agent on the same computer adds
- [Configuration](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/configuration.md): Every environment variable, Bridge TLS, protected senders

## Reference

- [Tool reference](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/tools.md): Server instructions, every tool and every argument, generated from the server
- [Results, refusals and limits](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/results.md): What each result field and refusal means, what to do next, and the fixed limits
- [How approvals work](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/safety.md): Previews, tokens and forms, and what each change needs

## How it works

- [Searching and reading mail](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/search.md): Search, counts, threads and message handles
- [Drafts and attachments](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/drafts.md): Drafts, replies, forwards and the allowed folder
- [Sending mail](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/sending.md): The guarded send path, aliases and the typed OK
- [Cleaning up mail](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/cleanup.md): Moves, read state, labels, draft deletion and unsubscribe
- [Folder rules, Sieve filters and saved rules](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/rules.md): Beta rules, previewed filters and the saved rules store
- [Recovery](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/RECOVERY.md): Recover from a lost response, the action log, undo and the audit trail

## Optional

- [Search index](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/search-index.md): Index coverage, rebuilds and background sync
- [MCP Apps views](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/mcp-apps.md): The thread view, the composer and the send review
- [IMAP IDLE](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/imap-idle.md): The optional new-mail watcher
- [Windows](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/windows.md): Native Windows support, what was and was not checked, and WSL2
- [AGENTS.md](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/AGENTS.md): Commands, layout, conventions and safety rules for changing the code
- [Contributing](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/CONTRIBUTING.md): How to contribute
- [Security policy](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/SECURITY.md): How to report a vulnerability privately
- [Development](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/development.md): Tests and offline checks
- [CI](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/ci.md): What GitHub Actions runs and when
- [Glama](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/docs/glama.md): The build settings Glama's listing uses to start the server without Bridge
- [Changelog](https://raw.githubusercontent.com/legalaspro/proton-mail-mcp/main/CHANGELOG.md): What changed
