mailmate-mcp

An MCP server that gives Claude (and other MCP clients) direct access to MailMate, the macOS email client. Search, read, move, tag, and link emails without leaving your conversation.

Requirements

• macOS (MailMate is Mac-only)
• MailMate installed and configured with at least one IMAP account
• Python 3.11+
• uv

Installation

git clone https://github.com/huckncatch/mailmate-mcp
cd mailmate-mcp
uv sync

MCP Registration

Claude Code (global, all projects)

claude mcp add --scope user mailmate /path/to/mailmate-mcp/.venv/bin/mailmate-mcp

Or add manually to ~/.claude.json under "mcpServers":

"mailmate": {
  "type": "stdio",
  "command": "/path/to/mailmate-mcp/.venv/bin/mailmate-mcp",
  "args": [],
  "env": {}
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mailmate": {
      "command": "/path/to/mailmate-mcp/.venv/bin/mailmate-mcp"
    }
  }
}

Restart Claude Desktop after any change to server code or config.

Tools

Tool	Description
search_messages	Search by query string, tag, account, or mailbox. Supports body search.
get_message	Fetch full details and body for a message by its message:// URL.
list_mailboxes	List all mailboxes across all configured accounts with message counts.
list_tags	List all tags defined in MailMate Preferences → Tags.
get_message_link	Get the message:// link for a message and open it in MailMate.
open_message_in_mailmate	Navigate MailMate to a specific message.
move_message	Move a message to a different mailbox (syncs via IMAP).
tag_message	Add or remove tags on a message (syncs as IMAP keywords).

Messages are identified by message:// URLs derived from the RFC 2822 Message-ID header, e.g. message://%3Cabc123@example.com%3E. Use search_messages to find them.

How It Works

The server reads MailMate's on-disk message store at:

~/Library/Application Support/MailMate/Messages.noindex/IMAP/
  <account>/
    <mailbox>.mailbox/
      Messages/
        <uid>.eml

mailstore.py — filesystem and parsing layer. Walks the store, parses .eml files, and maintains an in-memory index for fast search. No MCP or AppleScript dependencies.

server.py — MCP boundary. Defines all tools via fastmcp and issues AppleScript calls to MailMate for actions that require IMAP sync (open, tag, activate).

Development

# Run the server directly (stdio transport)
uv run mailmate-mcp

# Or via the module
uv run python -m mailmate_mcp.server

There is no automated test suite. Manual testing is done by registering the server with Claude Desktop or Claude Code and exercising the tools in a conversation.