mu-mcp
Search and read your local mu-indexed email via MCP, and extract/open attachments.
health_check — verify the MCP server is running.
query — run a
mu findsearch expression (from:, subject:, date:, flag:attach, mime:application/pdf, etc.) and get matching messages; the tool description embeds the fullmu find/mu querysyntax guide.view — display emails by their file paths (paths obtained from
mu find --fields "l").get_attachment — extract attachment(s) from an email using
mu extract; saves them to a temp dir and optionally opens them with the OS default viewer.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mu-mcp find emails from Sarah about the project update"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mu-mcp: MCP Server for the mu Mail Indexer
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), andmu_helpfor the fullmureference 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
muindexClaude 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-mcpUsage
Run the MCP Server
uvx mu-mcpThe 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-mcpUse -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-mcpAdding a tool to view an email.
Adding a tool to find and download attachments.
Progressive disclosure of the
muman pages viamu_help.Add a
mu-mcpconsole script and useuvx mu-mcpas 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_contactsviamu 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 toolslist_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 marchFields: 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
andbetween 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
Scored across 5 tools
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.
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.
Five tools are well-scoped for a local email search/read server. Each tool earns its place; no bloat or missing essential primitive.
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
Related MCP Connectors
An MCP server that provides email capabilities, hosted on Alpic platform
An MCP server that provides email capabilities, hosted on Alpic platform
An MCP server that provides email capabilities, hosted on Alpic platform
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Related MCP Servers
- AlicenseAqualityDmaintenanceA 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.4114MIT
- AlicenseNot gradedqualityDmaintenanceAn 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.1MIT
- AlicenseAqualityCmaintenanceAn MCP server that enables Claude to directly access and manage email through IMAP. It provides tools for reading, searching, organizing, and drafting emails within your mailbox.9MIT
- AlicenseNot gradedqualityDmaintenanceA cross-platform MCP server that provides Claude with email access via IMAP, supporting multiple email providers and account management.MIT