mu-mcp

A small, read-only Model Context Protocol server that lets agents search and read a local Maildir indexed by mu. It exposes two tools:

• search_mail: search with mu's query language, returning bounded message metadata.

• read_mail: read one matching message as plain text, with a configurable output cap.

This connector does not send, delete, move, flag, or otherwise modify mail.

Requirements

• Python 3.10 or later

• mu installed and initialized/indexed for the account you want to use

• An MCP client that supports local stdio servers

Related MCP server: mbox-mcp

Install

From a checkout:

python -m pip install .

Or run directly from the repository with python -m mu_mcp.server after installing the package. For development, install python -m pip install -e '.[dev]'.

Configure an MCP client

The server communicates over stdio. Example configuration for clients that use the common mcpServers format:

{
  "mcpServers": {
    "mu-mail": {
      "command": "mu-mcp",
      "env": {
        "MUHOME": "/home/you/.mu",
        "MU_BIN": "/usr/bin/mu"
      }
    }
  }
}

MUHOME and MU_BIN are optional. MUHOME is passed to mu as --muhome; otherwise mu's normal configuration and MUHOME environment behavior apply. MU_MCP_TIMEOUT sets the per-command timeout in seconds (default 30). Keep stdout reserved for MCP: diagnostics are returned as tool errors.

Tools

search_mail(query, limit=20, sort="date", descending=true)

Accepts native mu query syntax. Examples:

from:alice@example.com subject:invoice
after:2025-01-01 before:2025-02-01
flag:unread
"project aurora" AND to:team@example.com

At most 100 results are allowed. Sorting is restricted to date, from, subject, or size. Results include common headers, flags, and message IDs; local filesystem paths are intentionally omitted.

read_mail(query, max_chars=12000)

Finds one matching result and asks mu view for its headers and plain-text content. Use a discriminating query, such as message-id:<id>, sender plus subject, and/or a date range. max_chars must be between 500 and 40,000. The result includes a truncated flag. Attachments are not extracted.

Privacy and safety

Email content is sensitive. This server runs locally and returns message data only to the connected MCP client, but that client or its model provider may process tool results under its own policies. Connect only clients you trust. Queries are passed as argument values directly to mu without a shell, and the server has no mail mutation tools. Message paths come from mu search results and are not accepted as user-provided filesystem paths.

Development

python -m pip install -e '.[dev]'
pytest

Tests mock the mu process and do not read your mailbox. See mu's query syntax for the full search language.

License

MIT. See LICENSE.