Mailmate

FreeNot checked

Enables searching, reading, moving, tagging, and linking emails in MailMate via MCP tools, allowing Claude to manage email without leaving the conversation.

by huckncatch

GitHub Embed

About

Enables searching, reading, moving, tagging, and linking emails in MailMate via MCP tools, allowing Claude to manage email without leaving the conversation.

README

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://%[email protected]%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.

from github.com/huckncatch/mailmate-mcp

Install Mailmate in Claude Desktop, Claude Code & Cursor

Recommended · one command, every IDE

unyly install mailmate-mcp

Installs into Claude Desktop, Claude Code, Cursor & VS Code — handles npx, uvx and build-from-source repos for you.

First time? Get the CLI: curl -fsSL https://unyly.org/install | sh

Or configure manually

Run in your terminal:

claude mcp add mailmate-mcp -- uvx --from git+https://github.com/huckncatch/mailmate-mcp mailmate-mcp

FAQ

Is Mailmate MCP free?

Yes, Mailmate MCP is free — one-click install via Unyly at no cost.

Does Mailmate need an API key?

No, Mailmate runs without API keys or environment variables.

Is Mailmate hosted or self-hosted?

Self-hosted: the server runs locally on your machine via the install command above.

How do I install Mailmate in Claude Desktop, Claude Code or Cursor?

Open Mailmate on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.

Related MCPs

Gmail

Read, send and search emails from Claude

by Google

Slack

Send, search and summarize Slack messages

by Slack

Runbear

No-code MCP client for team chat platforms, such as Slack, Microsoft Teams, and Discord.

by Community

Discord Server

A community discord server dedicated to MCP by [Frank Fiegel](https://github.com/punkpeye)