MCP Server Notmuch

What hgn/mcp-server-notmuch MCP server does

The hgn/mcp-server-notmuch MCP server connects an MCP client to a local email database managed by the notmuch command-line tool. Its primary mode is read-only: an agent can search messages and threads, inspect headers and bodies, review thread structure, find related conversations, and identify messages awaiting a response.

Attachment handling covers text files, PDFs, office documents, images, and calendar invites. The server can also search for attachments across a mailbox and resolve names to the email addresses found in messages. It does not send email. Drafts are written to a configured local maildir for later review and sending in a normal mail client.

How it works

The hgn/mcp-server-notmuch MCP server invokes the real notmuch CLI rather than the notmuch2 Python bindings. The notmuch executable must be available on PATH, or its path can be set in configuration. A missing configuration file uses the system notmuch binary and a built-in unrestricted all scope. Once a configuration file defines scopes, those configured scopes are authoritative.

Scopes let administrators constrain searches to named notmuch queries, such as personal mail or mailing lists. A tool can add a caller-supplied query to the selected scope. The server combines both queries with an AND operation, preventing an OR expression from escaping the scope boundary.

Results are not silently truncated. Callers can provide explicit result or character limits, and configured limits can cap message bodies, attachment text, and images. When a limit cuts output, the response indicates that more data exists.

Setup and configuration

Install the project with uvx --prerelease=allow mcp-server-notmuch when the PyPI package is available, or install it from the repository with the documented uv commands. The prerelease option is required because the project pins a prerelease MCP SDK.

The configuration file is normally $XDG_CONFIG_HOME/mcp-server-notmuch/config.toml, or ~/.config/mcp-server-notmuch/config.toml when XDG_CONFIG_HOME is unset. Use --config to select another file. Configuration can specify the notmuch binary and its own config path, search scopes, output limits, draft-maildir settings, draft sender and signature, wrapping width, attachment-size limits, and the user's email addresses.

PDF extraction requires pdftotext from poppler-utils. Office-document extraction requires either pandoc or libreoffice. Pillow is optional and can downscale oversized images instead of refusing them. Gource is optional for playing back an exported mailbox-history log.

Tools and capabilities

The read tier is always available and includes search, message and thread reading, thread overviews, message and thread counts, address lookup, attachment listing and reading, attachment search, scope listing, reply preparation, related-thread detection, and pending-reply tracking.

Passing --allow-drafts registers tools for creating and revising plain-text drafts. Draft operations require both a configured maildir and a From: value. Passing --allow-tags enables adding or removing tags on existing messages. Passing --allow-export DIR enables attachment and Gource-log exports within the named directory.

These flags control which tools are registered; disabled write capabilities are absent from the client's tool list. Existing message content is not modified by draft operations, and the server has no send capability.

Limitations and notes

The hgn/mcp-server-notmuch MCP server is designed for local notmuch databases and Maildirs, not hosted mailbox APIs. It cannot send mail through SMTP or sendmail. Its filesystem access is bounded by the notmuch database, configured drafts maildir, and—when export is enabled—the selected export directory.

Draft and tag operations are opt-in, while reading remains available without those flags. Reply tracking that uses direction="waiting" needs configured identity addresses or a readable notmuch primary email address. Without PDF, office-document, or image support dependencies, the relevant attachment operations report the missing requirement instead of providing the content.