ClipMCP

A standalone clipboard history MCP server for macOS. Monitors your system clipboard in real-time, stores history locally in SQLite, and exposes it to any MCP-compatible AI assistant — no third-party clipboard app required. All data stays on your machine.

What it does

• Captures text, HTML, and images from your clipboard automatically in the background
• Categorises each clip: error, code, url, email, path, sensitive, text
• Detects sensitive content (API keys, tokens, passwords) and flags it before your AI assistant sees it
• Semantic search — find clips by meaning, not just keywords (optional, local embeddings)
• Debug context bundling — say "fix this error" and your AI assistant automatically pulls recent error clips, code snippets, and logs together into one context block
• Exposes 9 MCP tools your AI assistant calls automatically based on conversation context

Requirements

• macOS (Linux/Windows support planned)
• Python 3.11+
• Any MCP-compatible client (Cursor, VS Code, Claude Desktop, or others)

Installation

1. Clone the repo

git clone https://github.com/susmetaa01/clipmcp.git
cd clipmcp

2. Install the package

pip install -e .

3. (Optional) Semantic search

Adds meaning-based search using a local all-MiniLM-L6-v2 model (~80 MB, runs fully offline):

pip install -e ".[semantic]"

4. Verify it starts

python -m clipmcp

You should see:

ClipMCP monitor starting (poll interval: 500ms, max clip size: 50000 bytes)
ClipMCP server started.

Press Ctrl+C to stop.

Connecting to your AI client

ClipMCP works with any MCP-compatible client over stdio transport. Pick yours below.

MCP Inspector (browser UI — great for testing before connecting to a client)

npx @modelcontextprotocol/inspector python -m clipmcp

Opens http://localhost:5173 — call any of the 9 tools directly, inspect inputs and outputs, no client setup required.

Cursor

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "clipmcp": {
      "command": "python3",
      "args": ["-m", "clipmcp"],
      "cwd": "/path/to/clipmcp/src"
    }
  }
}

Restart Cursor. Open AI chat in Agent mode — ClipMCP tools are available automatically.

VS Code (v1.99+ with GitHub Copilot)

Create .vscode/mcp.json in your workspace, or Cmd+Shift+P → "MCP: Add Server":

{
  "servers": {
    "clipmcp": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "clipmcp"],
      "cwd": "/path/to/clipmcp/src"
    }
  }
}

Open Copilot Chat → switch to Agent mode → ClipMCP tools appear in the tool list.

Note: VS Code uses "servers" (not "mcpServers") and requires "type": "stdio" explicitly.

Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "clipmcp": {
      "command": "python3",
      "args": ["-m", "clipmcp"],
      "cwd": "/path/to/clipmcp/src"
    }
  }
}

Fully quit and restart (Cmd+Q, not just close the window).

Other clients

• Continue.dev — open-source VS Code AI extension
• mcp-cli — lightweight terminal client

To find your Python path: which python3

Verifying it works

1. Copy any text to your clipboard
2. Open your AI client's chat
3. Ask: "What did I just copy?"

The assistant will call get_recent_clips and show your clipboard history.

For debug workflows:

1. Copy an error or stack trace from your terminal or IDE
2. Ask: "Fix this error" or "What's wrong?"

The assistant will call get_debug_context, which surfaces error clips first, then code, then everything else — no pasting required.

Available MCP Tools

Your AI assistant calls these automatically based on context. You never need to mention them by name.

Configuration

Settings are created automatically at ~/.clipmcp/config.json on first run.

{
  "poll_interval_ms": 500,
  "max_history_size": 10000,
  "auto_prune": true,
  "prune_after_days": 30,
  "detect_sensitive": true,
  "categories_enabled": true,
  "max_clip_size_bytes": 50000,
  "db_path": "~/.clipmcp/history.db"
}

Project structure

clipmcp/
├── pyproject.toml
├── README.md
├── CONTRIBUTING.md
├── src/
│   └── clipmcp/
│       ├── models.py
│       ├── config.py
│       ├── sensitive.py
│       ├── categorizer.py
│       ├── html_handler.py
│       ├── image_handler.py
│       ├── embeddings.py
│       ├── storage.py
│       ├── monitor.py
│       └── server.py
└── tests/

Known limitations

• Gaps when your client is closed — the monitor only runs while your AI client is open
• 500 ms polling — copying two things in very fast succession may miss the first
• Source app is best-effort — reflects the frontmost app at poll time, not the app that triggered the copy
• Screenshot errors not yet categorised — a screenshot of a stack trace is stored as image, not error. OCR support is on the roadmap

Roadmap

Data privacy

• All data is stored locally in ~/.clipmcp/ — nothing leaves your machine
• Embeddings are computed locally using a bundled model
• Sensitive content is flagged and never shown to your AI assistant in full unless you explicitly request it

Contributing

See CONTRIBUTING.md for architecture, design patterns, database schema, and how to add new features.

License

MIT