# hgn/mcp-server-notmuch [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/hgn/mcp-server-notmuch  
**GitHub Stars:** 1  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hgn-mcp-server-notmuch

## Description
notmuch MCP server. Wraps the notmuch CLI to give your LLM access to a local Maildir: full-text search, tag filtering, thread view, attachment reading (PDF, office docs, .ics), related-thread lookup, and unanswered-mail tracking. Optionally write plain-text drafts into a local maildir (--allow-drafts) or manage tags (--allow-tags). No SMTP, no sendmail.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "mcp-server-notmuch": {
    "command": "npx",
    "args": ["-y","hgn-mcp-server-notmuch"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/hgn-mcp-server-notmuch/readme_