Mermoz MCP server

mermoz mcp runs an MCP server on stdio that gives AI agents the user's Mermoz mailbox as 29 tools: search, read, sort, draft, Drive files and more. It is local: it runs on the user's Mac, next to Mermoz.app, and talks to the app's daemon over a Unix socket. There is no hosted or remote (Streamable HTTP) endpoint: Mermoz has no server of its own that holds mail.

• Requires: Mermoz.app installed and running (macOS 26 or later), signed in to Gmail. If the app isn't running, tools answer "Mermoz isn't running. Ask the user to open Mermoz.app."
• Command: mermoz mcp once the CLI is in PATH (Mermoz › Settings › Developer › Install in PATH), or the full path /Applications/Mermoz.app/Contents/Resources/mermoz mcp.
• Protocol version: 2025-06-18; capability tools.
• Sending: send_draft moves the draft to the user's Review lane and returns approval_required unless the user enabled agent sending. Tell the user; do not retry.

Add Mermoz to Claude Code

claude mcp add mermoz -- mermoz mcp
# for every project: claude mcp add --scope user mermoz -- mermoz mcp

Add Mermoz to Claude Desktop

Claude Desktop does not read your shell's PATH, so use the full path. In Claude Desktop, Settings › Developer › Edit Config opens ~/Library/Application Support/Claude/claude_desktop_config.json; add:

{
  "mcpServers": {
    "mermoz": {
      "command": "/Applications/Mermoz.app/Contents/Resources/mermoz",
      "args": ["mcp"]
    }
  }
}

Then quit and reopen Claude Desktop.

Add Mermoz to Codex

codex mcp add mermoz -- mermoz mcp

Or in ~/.codex/config.toml:

[mcp_servers.mermoz]
command = "mermoz"
args = ["mcp"]

Any other MCP client

Launch mermoz mcp (or /Applications/Mermoz.app/Contents/Resources/mermoz mcp) as a stdio server: newline-delimited JSON-RPC 2.0 on stdin and stdout. Discovery documents: server.json (official MCP registry format) and /.well-known/mcp.json.

Tools

search_mail

Full-text search across all local mail (instant, offline). Supports from:, to:, subject: prefixes. Returns threads best match first.

list_threads

List threads (issues) filtered by status/project/account, newest first. Statuses: unread, todo, waiting, in_progress, backlog, review, done, archive, deleted. Projects are the user's Gmail labels; each thread lists its projects and the AI's pending suggestion. suggested: true for threads with a pending suggestion, or {status, projects} for one destination listed by column_suggestions. conversations: one row per conversation (Gmail threads with the same people about the same matter, as the user sees them), each with conversation_threads; kind: ["feed", "list"] for automated senders and mailing lists.

get_thread

Read a whole thread: every message's plain-text body, recipients and attachment ids. With conversation, every message of the conversation it belongs to (each with its thread_id), plus its people, files and links.

split_conversation

Take a thread out of the conversation Mermoz grouped it into (when it is a different matter). Final: it is never grouped with them again.

merge_conversations

Join the conversations of two or more threads into one (same people, same matter).

list_files

Files shared in any conversation, newest first, with their attachment id (read with get_attachment) and thread.

update_thread

Change a thread's status, priority (0 none,1 urgent,2 high,3 normal,4 low), projects (Gmail labels: add_projects/remove_projects, or projects to replace) or due date (YYYY-MM-DD, null clears). 'deleted' moves the thread to Gmail Trash.

accept_suggestions

Accept the AI's pending suggestion (status, projects, priority) for threads; they count as read. Pass ids, or column (a status) to accept that column's pending suggestions — all of them, or only the group given by to_status/to_projects as listed by column_suggestions.

reject_suggestions

Turn down the AI's pending suggestion for threads: they stay where they are and are not suggested again.

column_suggestions

The AI's pending suggestions in status columns, grouped by target (status + projects) with counts, and how far background sorting has got (classified of total). Nothing moves until accepted.

stop_resort

Stop a whole-mailbox sort and clear every suggestion on read threads that nobody reviewed. Accepted and turned-down suggestions are kept; Unread mail keeps its own.

No parameters.

get_attachment

Get an attachment's local file path (readable offline); text attachments also return their content.

create_draft

Create a draft. With thread_id it is a reply and recipients/subject default from the thread. Drafts never send by themselves. Attachments are copied into Mermoz; Gmail sends at most 25 MB of files per email.

send_draft

Ask to send a draft. Unless the user enabled agent sending, the draft goes to the user's Review lane and this returns approval_required: tell the user, do not retry.

search_contacts

Search the user's directory, built automatically from email signatures: names, titles, companies, phones, addresses, websites. Empty query lists recent contacts.

list_labels

The user's Gmail labels (mailboxes) with ids, accounts and thread counts.

No parameters.

list_statuses

Workflow statuses.

No parameters.

list_projects

Projects: the user's Gmail labels. A thread can be in several.

No parameters.

chat_about_thread

Ask the user's own AI (the one allowed for the thread's account in Mermoz) about a thread; it sees the thread, its people, status and the user's earlier mail with them, and may search the web. The conversation is kept with the thread and shown in the app. Returns the answer and proposed actions (status, project, follow_up date, draft_reply body); nothing is applied: use update_thread or create_draft to act. Without a question, returns the conversation so far.

thread_drive_files

Google Drive files of a thread: those linked in its messages (with access: ok, no_access or not_connected), files shared by or with its participants, and its attachments already saved to Drive. Needs the account's Drive connected in Mermoz.

read_drive_file

A Google Drive file's text: Docs as Markdown, Sheets as CSV (first sheet), Slides as text, plain-text files as they are. Cached locally.

search_drive

Search the account's Google Drive by name and content; without a query, the files the user opened most recently.

save_attachment_to_drive

Save an attachment to the user's Google Drive, in Mermoz/<the thread's project> (created if missing). Returns the folder and an Open in Drive link; saving again returns the same file. Sharing files stays with the user in the app.

feed

The user's Feed: every open thread as a card (one thing to do), in sections now, today, week, waiting, later, ordered by deadline then urgency. Each card has a kind (reply, decision, sign, promise, event, payment, intro, waiting, cleanup, reading, other), plain-language reasons, the deadline and amount written in the mail, and the AI's words when written. Automated mail and newsletters come as batch cards listing their threads.

snooze_thread

Later: hide threads from the Feed until a time (Unix ms) or until new mail arrives in them. until null brings them back now.

plan_bulk_action

Plan a change to many threads from a plain-words instruction ("archive all messages past 5 months not in done"), the way the user's Ask Mermoz bar does: the user's own AI turns it into a typed plan (filters + set status / add or remove project / mark read or unread / later / delete to Trash; nothing can send, reply or forward), and Mermoz previews it: a sentence per step, how it was understood, counts per status and sample subjects. Nothing changes. Pass plan (the same JSON shape as a returned plan) instead of sentence to skip the AI. Show the user the summary, then call run_bulk_action.

run_bulk_action

Run a plan from plan_bulk_action. confirm must be the plan's total (the number of threads it changes), as a confirmation that the preview was read. Applies in batches and returns the run id for undo_bulk_action.

undo_bulk_action

Put every thread a bulk run changed back as it was.

submit_feedback

Report friction with these tools (missing option, confusing result, slowness) so Mermoz can improve.