Skip to main content
Glama
second-brain-imap

second-brain-imap

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.

Related MCP server: email-mcp

What it is careful about

  • Read-only on the wire. Mailboxes are opened with EXAMINE, data is fetched with BODY.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

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.

Available Tools

4 tools
mail_list_foldersMail List FoldersA
Read-only

List the mailboxes (folders and labels) with their message and unread counts.

Inputs: no named parameters. Returns: result

mail_readMail ReadA
Read-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 RecentB
Read-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.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 4 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to read, search, and manage emails via IMAP with secure, read-only access to email accounts.
      6
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude to read, search, draft, send, flag, and move email across multiple IMAP/SMTP mailboxes while keeping credentials local.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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