second-brain-imap
Searches and reads a Proton Mail mailbox exposed through Proton Mail Bridge: lists folders and labels with message/unread counts, searches messages by text, sender, recipient, subject, date range, folder or unread status, retrieves recent messages, and reads individual messages as paged plain text with attachments listed. Access is strictly read-only — nothing can be sent, deleted, moved or marked as read.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@second-brain-imap search my inbox for unread emails from my accountant this week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
second-brain-imap
An MCP server that lets Claude search and read an IMAP mailbox. It cannot send, delete, move or mark anything: there is no code in it that changes a mailbox.
It was built for Proton Mail Bridge, which decrypts a Proton
mailbox on the machine it runs on and serves it as IMAP on 127.0.0.1. Any IMAP server with TLS
should work; Bridge is the one it is tested against.
A sibling of second-brain-joplin, on the same stack: FastMCP, stdio for a client on the same machine, streamable HTTP with GitHub sign-in for a Claude custom connector.
Status: 0.1.0, on PyPI. It runs against one mailbox.
What Claude gets
Tool | What it does |
| The mailboxes (folders and labels) with message and unread counts |
| Search by text, sender, recipient, subject, dates, folder, unread; newest first |
| The last days of one mailbox, newest first |
| One message as plain text, a page at a time; attachments listed, never downloaded |
Details: docs/tools.md.
Related MCP server: email-mcp
What it is careful about
Read-only on the wire. Mailboxes are opened with
EXAMINE, data is fetched withBODY.PEEK, and one small module (imap.py) is the only place a command leaves from. Reading a message does not mark it as read.Mail is written by strangers. HTML is reduced to the text a person would see: hidden elements, scripts, styles and comments are dropped, and nothing is fetched. Invisible and direction-changing characters are removed from every name, subject and body. Every answer says that its text is information, not instructions.
Spam and Trash are hidden unless you switch that off, and so is any mailbox you list. A hidden message is withheld wherever else the mail server shows a copy of it (Bridge's All Mail contains Trash; a label can too).
Always encrypted, always verified. TLS to the mail server with the certificate checked, even on
127.0.0.1. Bridge's self-signed certificate is pinned, not waved through.Bounded. Attachments are never fetched, a message's text is paged, searches return at most 50 results, and a remote caller is rate-limited.
Quiet logs. One line per tool call: tool, caller, client, outcome, duration. Never a search term, a subject, an address or a credential.
More in SECURITY.md.
Try it with Proton Mail Bridge
Bridge running and signed in on this machine. Installed from PyPI, a copy reads its settings
from the environment or from the file named with --env-file
(docs/configuration.md):
uv tool install second-brain-imap
mkdir -p ~/.config/second-brain-imap
# serve.env: SBI_IMAP_USERNAME, SBI_IMAP_PASSWORD (Bridge's, not Proton's) and SBI_IMAP_TLS_CERT,
# a full path where pin-cert saves the certificate (`~` is not expanded in the file).
# .env.example lists every setting.
"${EDITOR:-vi}" ~/.config/second-brain-imap/serve.env
second-brain-imap pin-cert --env-file ~/.config/second-brain-imap/serve.env
second-brain-imap check --env-file ~/.config/second-brain-imap/serve.env
claude mcp add second-brain-imap -- second-brain-imap serve --env-file ~/.config/second-brain-imap/serve.envOr from a checkout, where the .env beside pyproject.toml is read:
git clone https://github.com/second-brain-tools/second-brain-imap && cd second-brain-imap
cp .env.example .env # then set the username and the Bridge password in it
uv run second-brain-imap pin-cert # saves Bridge's certificate where .env says
uv run second-brain-imap check # signs in once and prints counts
uv run second-brain-imap folders # every mailbox, and which a client can openThen add it to Claude Code as a stdio server:
claude mcp add second-brain-imap -- uv --directory "$PWD" run second-brain-imap serveSettings: docs/configuration.md
Bridge specifics (the Bridge password, the certificate, how it lays out mail, what its search misses): docs/proton-mail-bridge.md
As a Claude custom connector, for claude.ai and the apps: docs/remote-access.md
Development
uv sync
uv run pytest --cov-fail-under=90 # the suite needs no mail server
uv run mypy
uvx pre-commit run --all-files # ruff, actionlint and file checks, as CI runs them
uv run scripts/smoke.py # installs the checkout with uvx and talks MCP to itThe tests run against an in-memory mail server (tests/fakes.py) that answers in the shapes a live Bridge 3.27 gave through IMAPClient 4.3.
Sign-in, the audit log, HTTP serving and the settings-file rules are
second-brain-core's, shared with
second-brain-joplin: fix shared code there, release it, then move this package's pin. To try an
unreleased core change, point uv at a checkout for the moment, and don't commit it
([tool.uv.sources] second-brain-core = { path = "../second-brain-core", editable = true }).
CI runs these on GitHub (checks.yml): Python 3.11 to 3.15 on Linux, and 3.13 on macOS and Windows, then the smoke test of the built wheel on all three. Dependabot proposes dependency updates weekly. Releases go to PyPI from a signed tag (docs/releasing.md).
License
Copyright (C) 2026 John McKenzie
second-brain-imap is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See LICENSE for the full text.
In short: run it and change it as you like. If you pass copies on, or change it and let other people use your version over a network, you must offer them the source under the same license.
Available Tools
4 toolsmail_list_foldersMail List FoldersARead-only
List the mailboxes (folders and labels) with their message and unread counts.
Inputs: no named parameters. Returns: result
mail_readMail ReadARead-only
Read one message as plain text, a page at a time for long ones.
Returns up to max_chars characters of the text starting at offset. When
next_offset is set, call again with offset=next_offset for the rest.
Attachments are listed by name, type and size; their content is not
available. Reading does not mark the message as read.
Inputs: message_id (required), offset, max_chars. Returns: One message, with a window of its text.
mail_recentMail RecentBRead-only
List the mail that arrived in the last days days in one mailbox, newest first.
Inputs: days, limit, folder, unread_only. Returns: Messages matching a search, newest first.
mail_searchMail SearchARead-only
Search mail, newest first. Every argument given must match.
text looks in the whole message, sender in From, recipient in To and
Cc, subject in the subject; each matches a word or phrase exactly as
written, in any letter case. since is the first day included and before
the first day left out. folder is a name from mail_list_folders; without
it the whole mailbox is searched. Read a result with mail_read and its id.
Inputs: text, limit, since, before, +5 more. Returns: Messages matching a search, newest first.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct role: folder listing, query-based search, recency listing, and message reading. The only real overlap is mail_recent versus mail_search, since a recent-window listing can be approximated with a `since` search, but the descriptions make the boundary (fixed N days, single mailbox) reasonably clear.
All four tools use a uniform `mail_` prefix plus a snake_case verb or verb_noun (list_folders, search, recent, read). The convention is predictable and readable throughout.
Four tools is on the thin side but well matched to a focused read-only mailbox surface: discover folders, find mail, list recent mail, read a message. No tool feels redundant enough to remove, though the set is minimal.
Core read workflows are covered (folders, search, recent, paged read), but there is no way to send, reply, move, delete, or flag messages, and attachment content is inaccessible. For a mail domain this leaves notable gaps, even if a read-only design is intentional.
Maintenance
Related MCP Connectors
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Your mailboxes in ChatGPT and Claude: Gmail, iCloud, Fastmail, any IMAP. Passwords stay yours.
Connect Gmail, iCloud Mail, Outlook, Yahoo Mail, Fastmail and other IMAP inboxes to ChatGPT, Claude and compatible AI assistants. Find emails by meaning across languages with semantic search. Ask AI to find customer conversations, summarize deadlines and draft follow-ups. Give a sales rep access to a shared outreach inbox or bring email into a compatible CRM. Share an iCloud custom-domain inbox with teammates without their own Apple ID or iCloud+ plan. Search results may be incomplete or stale; separate permissions control mail actions.
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to read, search, and manage emails via IMAP with secure, read-only access to email accounts.6MIT
- FlicenseNot gradedqualityBmaintenanceEnables Claude to read, search, draft, send, flag, and move email across multiple IMAP/SMTP mailboxes while keeping credentials local.-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to securely access IMAP mailboxes with read-focused tools for searching, reading, listing messages, and creating drafts, while deliberately preventing sending or deleting emails.MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude to read-only browse, search, and fetch emails from a Proton Mail inbox through Proton Bridge IMAP, with no capabilities to send, move, flag, or delete.MIT