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 -s user maus -- npx maus-mcp@latest

The -s user flag installs Maus globally for your user so it works in every project. Without it, the MCP only loads in the directory where you ran the command.

Restart Claude Code (close every session, open a new one) 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