protonmail-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PROTONMAIL_MCP_MODE | No | Capability preset: read, draft, organize, send, delete | read |
| PROTONMAIL_MCP_POLICY | No | Optional policy file with capability overrides and limits | ~/.config/protonmail-mcp/policy.toml |
| PROTONMAIL_BRIDGE_HOST | No | Bridge host | 127.0.0.1 |
| PROTONMAIL_BRIDGE_TIMEOUT | No | Socket timeout in seconds | 30 |
| PROTONMAIL_BRIDGE_PASSWORD | Yes | Bridge mailbox password (required) | |
| PROTONMAIL_BRIDGE_USERNAME | Yes | Your Proton address (required) | |
| PROTONMAIL_BRIDGE_IMAP_PORT | No | Bridge IMAP port | 1143 |
| PROTONMAIL_BRIDGE_VERIFY_TLS | No | Bridge uses a self-signed certificate | false |
| PROTONMAIL_BRIDGE_IMAP_SECURITY | No | starttls (Bridge 3.x on 1143) or ssl (direct TLS) | starttls |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Access to a Proton Mail mailbox through a local Proton Bridge instance. Active policy: mode=read, capabilities: none (read-only). Use list_folders to discover folders and labels, list_emails for recent mail, search_emails for full-text search, and read_email to read one message by its Message-ID. Tools outside the active mode are not registered.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_foldersA | List every folder and label of the mailbox. Use this first when you do not know where a message lives; the returned names are valid values for other tools. |
| list_emailsA | List the most recent messages of a folder, newest first. Args: folder: Folder or label name, as returned by list_folders. limit: Maximum number of messages to return (1-100). unread_only: Only return unread messages when true. since_days: Only return messages from the last N days when set. sender: Only return messages whose From header contains this text. subject: Only return messages whose Subject header contains this text. before: Cursor from a previous page's next_cursor to continue listing. |
| search_emailsA | Search messages, newest first. All filters combine with AND. Args: query: Full-text across headers and body; empty matches everything. folder: Folder or label name to search in, as returned by list_folders. limit: Maximum number of messages to return (1-100). sender: Substring match on the From header. recipient: Substring match on the To header. subject: Substring match on the Subject header. since_days: Only messages received in the last N days. before_days: Only messages received before N days ago. unread_only: Only unread messages when true. has_attachment: Only messages carrying an attachment. IMAP cannot search on this, so up to 200 newest candidates are checked with BODYSTRUCTURE; the result reports how many were scanned and whether the set was truncated. |
| read_emailA | Read one full message, identified by the Message-ID returned by list_emails or search_emails. Returns headers, decoded text body, attachment names, and flags. Args: message_id: Full Message-ID header value, including angle brackets. folder: Folder the message is in. max_chars: Maximum body characters to return; longer bodies are truncated. |
| get_statusA | Counts of total and unread messages per folder, without fetching messages. Args: folder: A single folder name, or omit to get every selectable folder. |
| daily_digestA | Compact digest of a folder: unread count plus recent message summaries (subjects and senders only, no bodies). Args: folder: Folder to summarize. days: Window in days (default 1). limit: Maximum messages in the digest (1-100). |
| get_threadA | Reconstruct a conversation around a message using References/In-Reply-To, searching All Mail. Returns messages in chronological order. Args: message_id: Message-ID of any message in the thread. folder: Folder containing that message (used as a fallback if All Mail is absent). limit: Maximum messages in the thread (1-100). |
| list_attachmentsA | List a message's attachments (names, content types, sizes) without saving anything to disk. Args: message_id: Message-ID of the message. folder: Folder containing the message. |
| save_attachmentA | Save one attachment into the local sandbox directory. Files are never overwritten and never leave the sandbox. Args: message_id: Message-ID of the message. folder: Folder containing the message. filename: Exact attachment filename; omit when the message has exactly one. index: Attachment position (0-based) when filenames are ambiguous. |
| export_emailA | Export a full message as .eml into the local sandbox directory. Args: message_id: Message-ID of the message. folder: Folder containing the message. filename: Optional target filename; defaults to the Message-ID plus .eml. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| folders | Every folder and label, with IMAP flags and selectability |
| status | Total and unread counts per selectable folder |
TDQS
Scored across 10 tools
Tools mostly target distinct actions or resources, but list_emails and search_emails overlap in filtering, and get_status and daily_digest both report unread counts. An agent can infer the difference from descriptions, but there is mild potential for misselection.
Names mostly follow a verb_noun pattern: list_folders, list_emails, search_emails, read_email, get_status, get_thread, list_attachments, save_attachment, export_email. daily_digest is the only noun-phrase outlier, a minor inconsistency.
10 tools is well-scoped for an email access server; each tool covers a distinct capability without obvious redundancy. The count is neither too thin nor too heavy.
The surface covers read-oriented mailbox operations well: folders, listing, search, read, threads, attachments, and export. However, it lacks send/compose, delete, move, and label/mark-read operations, which are notable gaps for a full email lifecycle.