hgn/mcp-server-notmuch

An MCP server that exposes a local notmuch email
database to an LLM client such as Claude. It is read-first: searching,
reading, and understanding mail is always available; writing anything
(drafts, tags, exported files) requires an explicit opt-in flag and is
confined to clearly bounded locations.
**It never sends mail.** There is no send capability anywhere in this
codebase, in any mode, with any flag. Drafts are written to a local maildir
for you to review and send yourself in a real mail client.
What it does
- Searches and reads your mail (threads, single messages, attachments,
calendar invites, office documents, images) via the real notmuch CLI.
- Understands scopes: a named, pre-configured notmuch query (e.g. "personal
mail" vs. "mailing lists") that every search is confined to unless you ask
otherwise.
- Answers "what's still unanswered" and "who owes me a reply" (mail_pending),
"has this come up before" (mail_related_threads), and gives a
token-cheap overview of a long thread before you read all of it
(mail_thread_overview).
- Optionally composes and revises plain-text drafts (--allow-drafts),
tags messages (--allow-tags), or exports attachments and a
Gource visualization of your mailbox history to a
directory you name (--allow-export DIR).
What it does not do
- It does not send mail. Ever.
- It does not modify your mail in any way unless you pass --allow-tags
(tagging) or --allow-drafts (writing a new file into a drafts maildir).
Neither flag lets it touch existing messages' content.
- It does not read or write outside the notmuch database, the configured
drafts maildir, and (only with --allow-export) the configured export
directory.
- It does not require or use the notmuch2 Python bindings, so no compiler
is needed to install it.
Install
From PyPI (once published)
From source
The --prerelease=allow is required because this project pins a
pre-release of the mcp SDK (see SDK version below); it is
not optional.
System requirements
- notmuch (the CLI, not just the library) on PATH or pointed to via
notmuch.binary in the config.
- poppler-utils (pdftotext) to read PDF attachments. Without it,
mail_read_attachment on a PDF names the missing package.
- pandoc or libreoffice to read office documents (doc/docx/odt/rtf).
Without either, the error names both options.
- Optionally, Pillow (pip install 'mcp-server-notmuch[image]') to let
oversized image attachments be downscaled instead of refused.
- Optionally, Gource to actually play back the log
mail_export_gource writes.
MCP client configuration
Claude Code
Read-only (the default: search and read tools only):
With drafts enabled (also allows revising/tagging as needed):
Or by hand in .mcp.json:
Claude Desktop
Add to claude_desktop_config.json (read-only default):
With drafts enabled:
Configuration
The server reads $XDG_CONFIG_HOME/mcp-server-notmuch/config.toml
(~/.config/mcp-server-notmuch/config.toml if XDG_CONFIG_HOME is unset),
or a path given with --config. A missing file is not an error: the server
falls back to the system notmuch binary and a single built-in scope
all with an empty query. Once a file exists, [scopes] is authoritative
and all is no longer implied.
See config.example.toml for a fully commented
reference file. Summary of every key:
| Section | Key | Default | Meaning |
|---|---|---|---|
| [notmuch] | binary | "notmuch" | Path or bare name of the notmuch binary. |
| | config | notmuch's own default | Path passed as NOTMUCH_CONFIG. |
| [limits] | max_body_chars | unset (unlimited) | Message body truncation point; unset means full body every time. |
| | max_attachment_chars | unset (unlimited) | Attachment/office/calendar text truncation point; unset means full text every time. |
| | max_image_bytes | 5242880 | Image size ceiling; downscaled with Pillow if larger, else refused. |
| [scopes] | default | *(required once [scopes] exists)* | Scope used when a tool call omits scope. |