maus-mcp

MCP server that gives Claude Code, Cursor, Codex and other MCP clients access to your Maus clipboard on macOS.

Local-only. No cloud. No clipboard content ever leaves your Mac. Respects your Maus tier (Free vs Pro) automatically.

Why

When Claude writes you an email, a SQL query, a regex or a snippet, copying it back out of the chat terminal drags monospace formatting, markdown asterisks and extra whitespace into your destination app.

With Maus + this MCP, the agent can put text straight into your Maus history. You paste from Maus into Mail / Slack / wherever — clean.

It also lets the agent search, list, and tidy your clipboard history, including OCR text from screenshots.

Requirements

• macOS (Maus is macOS-only; this MCP reads its local SQLite).
• Maus installed and running.
• Node.js ≥ 20.

Install

Claude Code

claude mcp add maus npx maus-mcp@latest

Open a new Claude Code session and try:

"Maus, show me my last 5 clipboard items"

Cursor

Add to your Cursor MCP config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "maus": {
      "command": "npx",
      "args": ["maus-mcp@latest"]
    }
  }
}

Other MCP clients

Anything that supports the Model Context Protocol stdio transport. Run npx maus-mcp@latest directly.

Tools

Tool	What it does
list_recent	Latest items chronologically, with filters.
search	Substring search across content, titles, source apps, URLs, and OCR text of screenshots.
get	Fetch one item by id. For images: returns OCR + a token-light reduced JPEG.
set_title	Rename an item. Lets the agent organise the clipboard.
forget	Permanently delete one item (by id) or many (by filter).
add_item	Write a clean text item into Maus history. Maus Pro only.

Pro vs Free

The MCP follows your Maus tier exactly:

• Free: full access to the last 24 hours of history.
• Pro: full history + advanced filters (source_apps, content_patterns) + writes (add_item).

When the agent requests something beyond your tier, the response carries an upgrade link so the agent can offer it in context.

Upgrade to Maus Pro →

Privacy

• No clipboard content ever leaves your Mac.
• The server sends anonymous shape-only telemetry to the same Supabase the Maus already uses (tool name, duration, tier, status — never values, queries, or content).
• To opt out, set MAUS_MCP_TELEMETRY=off in your environment.

Development

git clone https://github.com/mausformac/maus-mcp.git
cd maus-mcp
npm install
npm run dev    # run with tsx (live TypeScript)
npm run build  # compile to dist/

Manual testing without an MCP client:

node test_get.mjs
node test_list_recent.mjs
node test_search.mjs
node test_set_title.mjs
node test_forget.mjs
MAUS_MCP_TIER_OVERRIDE=pro node test_add_item.mjs

License

MIT

Links

• Maus
• Model Context Protocol
• Report a bug