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 |
|---|---|
mail_list_folders |
The mailboxes (folders and labels) with message and unread counts |
mail_search |
Search by text, sender, recipient, subject, dates, folder, unread; newest first |
mail_recent |
The last days of one mailbox, newest first |
mail_read |
One message as plain text, a page at a time; attachments listed, never downloaded |
Details: docs/tools.md.
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.env
Or 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 open
Then add it to Claude Code as a stdio server:
claude mcp add second-brain-imap -- uv --directory "$PWD" run second-brain-imap serve
- Settings: 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 it
The 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.
Metadata
Release files for second-brain-imap 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| second_brain_imap-0.1.0.tar.gz | 243.2 kB | With provenance | Details for second_brain_imap-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| second_brain_imap-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for second_brain_imap-0.1.0-py3-none-any.whl |
Total release size: 303.0 kB
Release files / second_brain_imap-0.1.0.tar.gz
| Download URL | second_brain_imap-0.1.0.tar.gz |
|---|---|
| Size | 243.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3d10d38584f8a72bf8ffeea45a1b9f01dcf0a5f96ff54c2920dfbf1ba5ae8276
|
|
BLAKE2b-256 checksum How to use checksums |
d61bcdfae87354336dc19daf90e1644fd53d5039dc9e2006776e6ceccf464c0d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logRelease files / second_brain_imap-0.1.0-py3-none-any.whl
| Download URL | second_brain_imap-0.1.0-py3-none-any.whl |
|---|---|
| Size | 59.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
30a40c388c6c2281791cfaf009451484a5a30ac85abaccddafe81dc9c457aef5
|
|
BLAKE2b-256 checksum How to use checksums |
0777e70c45a02b219b4b0de4a5b30b4673cf18d6afca183ca175fbef52f1ee01
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logSecurity for second-brain-imap 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for second_brain_imap-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.