Skip to main content
Glama

mu-mcp: MCP Server for the mu Mail Indexer

PyPI Python GitHub release MCP GitHub license

A Model Context Protocol (MCP) server for querying your local mu mail index. This server enables fast, structured mail search from Claude Desktop and other MCP clients.

Features

  • Stdio MCP server for easy integration

  • Tools: search_emails, view_emails (HTML-only emails converted to text), view_thread (reads a conversation from one message), find_contacts (resolves names to email addresses), list_attachments, open_attachment (saves to a temp dir and optionally opens with the default OS viewer), and mu_help for the full mu reference on demand.

  • Small context footprint: a short query guide lives in the tool description; the full man pages are only loaded when the model asks for them.

  • Fast, flexible mail search using the mu index

  • Claude Desktop ready: simple installation and config

  • Python, uv, and MCP SDK based

Related MCP server: Gmail Plugin MCP Server

Installation

Requires mu installed and your mail indexed (mu init + mu index).

With uv installed, run the published package from PyPI without cloning the repository:

uvx mu-mcp

Usage

Run the MCP Server

uvx mu-mcp

The server communicates over stdio; normally your MCP client launches it using the configuration below.

Claude Desktop Integration

Add to your claude_desktop_config.json:

"mcpServers": {
  "email": {
    "command": "uvx",
    "args": ["mu-mcp"]
  }
}

The client needs uvx and mu on its PATH. If it cannot find uvx, use the absolute path returned by which uvx as the command.

Claude Code Integration

claude mcp add email -s user -- uvx mu-mcp

Use -s local instead to enable it only in the current project. Check it with /mcp in a new session.

Query

Ask Claude to find emails, e.g. "Find emails with a PDF attachment that were sent last April and open the PDF", "Show me the email I received from Alice last week", or "Find emails with the subject 'Meeting Notes'".

To read a conversation, pass any message path from search_emails to view_thread(path). It returns indexed messages oldest first, omits duplicate Message-IDs, and converts HTML-only bodies to text. The defaults are 30 messages and 20,000 characters per message; increase max_results or max_chars if the output is truncated.

Use find_contacts("Alice") to resolve a name before searching. Its pattern is a case-insensitive regular expression matching names or addresses, such as @example\.com$. An empty pattern lists contacts. Results default to 30 contacts; use max_results to change the limit, or personal=True to restrict results to contacts seen in messages involving your personal addresses configured in mu.

Development

To run from a local checkout:

git clone https://github.com/danielfleischer/mu-mcp.git
cd mu-mcp
uv sync
uv run mu-mcp
  • Adding a tool to view an email.

  • Adding a tool to find and download attachments.

  • Progressive disclosure of the mu man pages via mu_help.

  • Add a mu-mcp console script and use uvx mu-mcp as the install method.

  • Describe when to use the server in its instructions, including email, inbox, messages, receipts, and attachments.

  • view_thread: show a whole conversation from one message.

  • find_contacts via mu cfind, to resolve a name to its addresses.

Run the tests with uv run python -m unittest discover -s tests. Integration tests use an isolated temporary mail index and are skipped if mu is unavailable.

Future ideas

  • Return attachment text (PDF, DOCX) from open_attachment; Claude Desktop can't read the saved file paths.

Available Tools

5 tools
list_attachmentsC

List the MIME parts (attachments, inline images, bodies) of one email.

Inputs: path (required). Returns: result

mu_helpA

Full mu reference, for when the short guide in search_emails isn't enough.

Topics: query (complete query language), fields (live list of fields and flags), find (search options), extract (attachment handling).

Inputs: topic (required). Returns: result

open_attachmentA

Save attachments of an email to a temp dir, optionally opening them.

Returns the saved file paths, so their contents can be read afterwards.

Args: path: message file path. pattern: case-sensitive PCRE matched against attachment file names, e.g. .*\.pdf$ or (?i)invoice. Default: all attachments. open_in_viewer: also open each file with the OS default application.

Inputs: path (required), pattern, open_in_viewer. Returns: result

search_emailsA

Search the local mail index with a mu query.

Returns one line per message: date | from | subject | path. Pass the path to view_emails or list_attachments.

Query syntax (quote phrases with double quotes; no shell is involved):

  • Bare words search from/to/cc/subject/body: invoice march

  • Fields: from: to: cc: contact: (any address) subject: body: maildir: (e.g. maildir:/Inbox) list: tag: file: (attachment name) mime: (attachment type, e.g. mime:application/pdf, mime:image/*)

  • Dates: date:2024-04..2024-04, date:2w.. (last 2 weeks), date:..2023, date:today.. (units: h d w m y)

  • Flags: flag:attach flag:unread flag:flagged flag:replied flag:personal flag:list flag:calendar

  • Operators: and, or, not, parentheses; implicit and between terms.

  • Wildcard suffix: budg*. Regex: subject:/re.?port/

  • Names match words in the address too: from:alice, from:amazon

Examples:

  • from:alice date:1w..

  • subject:"meeting notes"

  • mime:application/pdf and date:2025-04..2025-04

  • (from:bank or from:visa) and flag:unread

  • contact:bob and not flag:list

Args: query: the mu query. max_results: cap on returned messages; raise it or narrow the query if the result is cut off. sort: field to sort by. newest_first: reverse sort order (newest/Z first). include_thread: also return other messages from matching threads.

Inputs: query (required), sort, max_results, newest_first, +1 more. Returns: result

view_emailsA

Read emails (headers + body as text) given paths from search_emails.

HTML-only emails are converted to plain text.

Args: paths: message file paths. max_chars: per-message cap on returned text.

Inputs: paths (required), max_chars. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct action: search metadata, view message bodies, list MIME parts, save/open attachments, and read help. Boundaries are clear; no two tools overlap in purpose.

    Naming Consistency4/5

    Four tools follow a consistent verb_noun snake_case pattern (search_emails, view_emails, list_attachments, open_attachment), but mu_help deviates and list_attachments/open_attachment mix plural/singular. Minor deviations only.

    Tool Count5/5

    Five tools are well-scoped for a local email search/read server. Each tool earns its place; no bloat or missing essential primitive.

    Completeness3/5

    Search and view cover the core read path, but open_attachment saves files without any tool to read their contents afterward, creating a dead end for attachment processing. No update/tag operations either, though those may be outside the read-only scope.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that provides a seamless email management interface through Claude, allowing users to search, read, and send emails directly through natural language conversations.
      4
      114
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables Gmail integration, allowing users to manage emails (send, receive, read, trash, mark as read) directly through MCP clients like Claude Desktop.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A cross-platform MCP server that provides Claude with email access via IMAP, supporting multiple email providers and account management.
      MIT