{"id":"d5840ef6-20f5-45f8-9d13-4e2e0f1771af","slug":"danielfleischer-mu-mcp","kind":"mcp","name":"mu-mcp","summary":"MCP server for the mu email indexer and searcher.","owner":"danielfleischer","repoUrl":"https://github.com/danielfleischer/mu-mcp","license":"GPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":4,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-06-21T09:21:50.000Z","addedAt":"2026-10-21T04:01:54.830Z","logoUrl":"https://avatars.githubusercontent.com/u/22022514?u=6737285717134111e692bb180342670092a64a63&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["productivity","cloud-infra"],"tags":["claude-desktop","mu4e","email"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T03:23:10.131Z","sample":false,"url":"https://conduits.dev/tools/danielfleischer-mu-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"mu_mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"\n# mu-mcp: MCP Server for the `mu` Mail Indexer\n\n[![PyPI](https://img.shields.io/pypi/v/mu-mcp?color=blue)](https://pypi.org/project/mu-mcp/)\n[![Python](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fdanielfleischer%2Fmu-mcp%2Fmaster%2Fpyproject.toml&color=yellow)](https://github.com/danielfleischer/mu-mcp/blob/master/pyproject.toml)\n[![GitHub release](https://img.shields.io/github/v/release/danielfleischer/mu-mcp?color=orange)](https://github.com/danielfleischer/mu-mcp/releases)\n[![MCP](https://img.shields.io/badge/MCP-server-blueviolet)](https://modelcontextprotocol.io)\n[![GitHub license](https://img.shields.io/github/license/danielfleischer/mu-mcp?color=red)](https://github.com/danielfleischer/mu-mcp/blob/master/LICENSE)\n\nA Model Context Protocol (MCP) server for querying your local [`mu`](https://github.com/djcb/mu) mail index. This server enables fast, structured mail search from Claude Desktop and other MCP clients.\n\n<img src=\"assets/claude-screenshot.png\" width=\"500\"/>\n\n## Features\n\n- **Stdio MCP server** for easy integration\n- **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.\n- **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.\n- **Fast, flexible mail search** using the `mu` index\n- **Claude Desktop ready**: simple installation and config\n- **Python, uv, and MCP SDK** based\n\n## Installation\n\nRequires [`mu`](https://github.com/djcb/mu) installed and your mail indexed (`mu init` + `mu index`).\n\nWith [uv](https://github.com/astral-sh/uv) installed, run the published package\nfrom PyPI without cloning the repository:\n\n```sh\nuvx mu-mcp\n```\n\n## Usage\n\n### Run the MCP Server\n\n```sh\nuvx mu-mcp\n```\n\nThe server communicates over stdio; normally your MCP client launches it using\nthe configuration below.\n\n### Claude Desktop Integration\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n\"mcpServers\": {\n  \"email\": {\n    \"command\": \"uvx\",\n    \"args\": [\"mu-mcp\"]\n  }\n}\n```\n\nThe client needs `uvx` and `mu` on its PATH. If it cannot find `uvx`, use the\nabsolute path returned by `which uvx` as the command.\n\n### Claude Code Integration\n\n```sh\nclaude mcp add email -s user -- uvx mu-mcp\n```\n\nUse `-s local` instead to enable it only in the current project. Check it with `/mcp` in a new session.\n\n## Query\n\nAsk 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'\".\n\nTo read a conversation, pass any message path from `search_emails` to\n`view_thread(path)`. It returns indexed messages oldest first, omits duplicate\nMessage-IDs, and converts HTML-only bodies to text. The defaults are 30 messages\nand 20,000 characters per message; increase `max_results` or `max_chars` if the\noutput is truncated.\n\nUse `find_contacts(\"Alice\")` to resolve a name before searching. Its pattern is\na case-insensitive regular expression matching names or addresses, such as\n`@example\\.com$`. An empty pattern lists contacts. Results default to 30 contacts;\nuse `max_results` to change the limit, or `personal=True` to restrict results to\ncontacts seen in messages involving your personal addresses configured in `mu`.\n\n## Development\n\nTo run from a local checkout:\n\n```sh\ngit clone https://github.com/danielfleischer/mu-mcp.git\ncd mu-mcp\nuv sync\nuv run mu-mcp\n```\n\n- [x] Adding a tool to view an email.\n- [x] Adding a tool to find and download attachments.\n- [x] Progressive disclosure of the `mu` man pages via `mu_help`.\n- [x] Add a `mu-mcp` console script and use `uvx mu-mcp` as the install method.\n- [x] Describe when to use the server in its instructions, including email, inbox, messages, receipts, and attachments.\n- [x] `view_thread`: show a whole conversation from one message.\n- [x] `find_contacts` via `mu cfind`, to resolve a name to its addresses.\n\nRun the tests with `uv run python -m unittest discover -s tests`. Integration\ntests use an isolated temporary mail index and are skipped if `mu` is unavailable.\n\n### Future ideas\n\n- [ ] Return attachment text (PDF, DOCX) from `open_attachment`; Claude Desktop can't read the saved file paths.\n"}