Skip to main content
Glama
Sign In
protonmail-mcp-server

protonmail-mcp-server

by de-Blanck
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

protonmail-mcp-server

A Model Context Protocol (MCP) server for Proton Mail — read-only email access through Proton Bridge.

License: MIT Node.js

Connect Claude (or any MCP client) to your Proton Mail so it can search, list, and read your email — without your email ever leaving your machine.

Features

  • List folders with message and unread counts

  • List emails with pagination, sorted newest first

  • Search emails by sender, recipient, subject, body text, date range, read/flagged status

  • Read full email content by IMAP UID, including attachment metadata

  • Markdown and JSON response formats

  • Input validation via Zod schemas

  • Connection timeouts to prevent resource exhaustion

Related MCP server: ProtonBound

Prerequisites

  • Node.js 18+

  • Proton Bridge running on your machine with IMAP enabled

  • Your Bridge-specific IMAP credentials (not your Proton account password)

Finding your Bridge credentials

  1. Open Proton Bridge

  2. Click your account name

  3. Go to IMAP/SMTP settings (or Mailbox details)

  4. Note the Username (your email) and Password (Bridge-generated)

  5. Note the IMAP port (default: 1143)

Installation

npm install
npm run build

Or install globally from npm:

npm install -g protonmail-mcp-server

Configuration

Set these environment variables:

Variable

Required

Default

Description

PROTON_BRIDGE_USER

Yes

—

Bridge IMAP username (your email)

PROTON_BRIDGE_PASSWORD

Yes

—

Bridge-generated IMAP password

PROTON_BRIDGE_HOST

No

127.0.0.1

Bridge host

PROTON_BRIDGE_PORT

No

1143

Bridge IMAP port

Security: Configuration files containing your Bridge password are plaintext. Never commit them to version control or share them.

Adding to Claude Code

Add to your Claude Code MCP config (~/.claude/config.json or project-level):

{
  "mcpServers": {
    "protonmail": {
      "command": "node",
      "args": ["/path/to/protonmail-mcp-server/dist/index.js"],
      "env": {
        "PROTON_BRIDGE_USER": "your-email@proton.me",
        "PROTON_BRIDGE_PASSWORD": "your-bridge-password"
      }
    }
  }
}

Adding to Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "protonmail": {
      "command": "node",
      "args": ["/path/to/protonmail-mcp-server/dist/index.js"],
      "env": {
        "PROTON_BRIDGE_USER": "your-email@proton.me",
        "PROTON_BRIDGE_PASSWORD": "your-bridge-password"
      }
    }
  }
}

Available tools

proton_list_folders

List all mailbox folders with message and unread counts.

proton_list_emails

List emails in a folder (newest first) with pagination.

proton_get_email

Read a single email's full content by IMAP UID.

proton_search_emails

Search emails by sender, recipient, subject, body text, date range, read/flagged status.

Privacy & Security

  • Read-only — all four tools are read-only; no email modification, deletion, or sending

  • Localhost-only by default — connects to Proton Bridge on 127.0.0.1; TLS certificate validation is enforced for non-localhost connections

  • No disk caching — opens a fresh IMAP connection per request, no email data is stored on disk

  • No credential logging — your Bridge password is never logged, printed, or exposed in error messages

  • Input validation — all inputs are validated with Zod schemas; folder names are sanitized against control characters

  • Connection timeouts — all IMAP connections have configurable timeouts to prevent resource exhaustion

LLM Integration

This server implements the Model Context Protocol (MCP), making it compatible with any MCP client. When connected to an AI assistant like Claude, the assistant can:

  • Check for new or unread emails

  • Search for specific emails by sender, subject, or date

  • Read and summarize email content

  • Answer questions about your email (e.g., "What did Alice say about the quarterly report?")

  • List your mailbox folders and their message counts

All operations are read-only — the assistant cannot send, delete, or modify your emails.

Development

npm run dev    # Watch mode with auto-reload
npm run build  # Production build
npm start      # Run built server

License

MIT

Available Tools

4 tools
proton_get_emailGet Proton Mail EmailA
Read-onlyIdempotent

Retrieve a single email's full content by its IMAP UID, including body text and attachment metadata.

Use proton_list_emails or proton_search_emails first to find the UID of the email you want to read.

Args:

  • folder (string): The folder containing the email (default: 'INBOX')

  • uid (number): The IMAP UID of the email

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: Full email with headers, body text, and attachment list. Does NOT return attachment binary data.

Examples:

  • "Read email 1234" -> proton_get_email({ folder: "INBOX", uid: 1234 })

  • "Show me that email from Alice" -> first search, then get by UID

Inputs: uid (required), folder, response_format.

proton_list_emailsList Proton Mail EmailsA
Read-onlyIdempotent

List emails in a folder, sorted newest first, with pagination support.

Returns email summaries (subject, from, date, snippet) — not full bodies. Use proton_get_email to read an individual email's full content.

Args:

  • folder (string): Mailbox folder path (default: 'INBOX')

  • limit (number): Maximum emails to return, 1–100 (default: 20)

  • offset (number): Skip this many emails for pagination (default: 0)

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: Paginated list of email summaries with total count and pagination metadata.

Examples:

  • "Show my latest emails" -> proton_list_emails({ folder: "INBOX" })

  • "What's in my Sent folder?" -> proton_list_emails({ folder: "Sent" })

  • "Show me the next page" -> proton_list_emails({ folder: "INBOX", offset: 20 })

Inputs: folder, limit, offset, response_format.

proton_list_foldersList Proton Mail FoldersA
Read-onlyIdempotent

List all mailbox folders in the Proton Mail account with message counts and unread counts.

Use this tool to discover available folders before listing or searching emails.

Args:

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: A list of folders with path, message count, and unread count.

Examples:

  • "What folders do I have?" -> proton_list_folders()

  • "How many unread emails do I have?" -> proton_list_folders()

Inputs: response_format.

proton_search_emailsSearch Proton Mail EmailsA
Read-onlyIdempotent

Search emails in a folder using IMAP search criteria. Supports filtering by sender, recipient, subject, body text, date range, and read/flagged status.

Returns email summaries — use proton_get_email to read the full content of a specific result.

Args:

  • folder (string): Folder to search in (default: 'INBOX')

  • from (string, optional): Filter by sender email or name

  • to (string, optional): Filter by recipient email or name

  • subject (string, optional): Filter by subject text

  • body (string, optional): Search within email body

  • since (string, optional): Emails after this date (ISO 8601, e.g., '2025-01-01')

  • before (string, optional): Emails before this date (ISO 8601)

  • unseen (boolean, optional): Only unread emails

  • flagged (boolean, optional): Only starred/flagged emails

  • limit (number): Max results, 1–100 (default: 20)

  • offset (number): Pagination offset (default: 0)

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: Paginated list of matching email summaries.

Examples:

  • "Find emails from Alice" -> proton_search_emails({ from: "Alice" })

  • "Unread emails about quarterly report" -> proton_search_emails({ subject: "quarterly report", unseen: true })

  • "Emails from acme.com in March" -> proton_search_emails({ from: "acme.com", since: "2025-03-01", before: "2025-04-01" })

Inputs: folder, from, to, subject, +8 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: listing folders, listing emails, searching emails, and retrieving full email content. No overlap, even between list and search due to search's advanced filtering.

    Naming Consistency5/5

    All tools follow a consistent 'proton_verb_noun' snake_case pattern (list_folders, list_emails, search_emails, get_email). No deviation in style or convention.

    Tool Count4/5

    With 4 tools, the set is small but appropriate for a read-only email interface. It covers essential reading operations without unnecessary bloat, though some users might expect a few more common actions.

    Completeness3/5

    The tools cover the core read workflow (list folders, list/search emails, read full email) well, but completely lack write operations like send, delete, move, or mark as read. This is a notable gap for full email management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • ProtonScope

      dazzle-blip
      F
      license
      Not graded
      quality
      B
      maintenance
      A lightweight MCP server providing AI agents a scoped, read-and-draft-only view into Proton Mail via Proton Bridge, with code-enforced restrictions preventing external access or sending.
      -

    • ProtonBound

      dazzle-blip
      F
      license
      Not graded
      quality
      D
      maintenance
      A security-first MCP server that provides AI agents with a scoped, read-and-draft-only view into Proton Mail via Proton Bridge, ensuring no emails can be sent and access is restricted to configured workspaces.
      4
      -

    • proton-mail-mcp

      svgrepus
      A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that reads, searches, organizes, and deletes Proton Mail through the local Proton Mail Bridge, with read-only mode and sender authentication checks. It cannot send mail.
      102 npm
      MIT

    • proton-mcp

      purplehat93
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to interact with Proton Mail through a self-hosted server that works alongside Proton Mail Bridge. It provides read-only mailbox tools such as listing folders, searching mail, and retrieving messages while keeping Bridge isolated from the network.
      MIT