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.

Tool	Triggered when you say…
get_recent_clips	"what did I copy", "analyse this", "I just copied…"
search_clips	"find the AWS case", "look up the error from earlier"
semantic_search	"what was that Slack thread about Grafana"
get_debug_context	"fix this error", "what's wrong", "debug this"
pin_clip	"keep this clip", "pin that"
unpin_clip	"unpin clip 5"
delete_clip	"delete clip 3"
get_clip_stats	"how many things have I copied today"
clear_history	"clear my clipboard history"

---

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"
}

Setting	Default	Description
poll_interval_ms	500	How often to check the clipboard (ms)
max_history_size	10000	Max clips before pruning oldest
auto_prune	true	Automatically delete old clips
prune_after_days	30	Delete clips older than N days
detect_sensitive	true	Flag API keys, tokens, passwords
categories_enabled	true	Auto-categorise each clip
max_clip_size_bytes	50000	Truncate clips larger than 50 KB
db_path	~/.clipmcp/history.db	SQLite database location

---

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

Version	Feature	Status
v1.0	Text clipboard capture, SQLite storage, MCP tools	✅ Done
v1.1	Image clipboard capture (PNG/TIFF)	✅ Done
v1.2	HTML/rich text capture (web pages, Notion, Slack)	✅ Done
v1.3	Error-aware tagging (error category)	✅ Done
v2.5	Semantic search (local embeddings)	✅ Done
v2.6	Debug context bundling	✅ Done
v2.7	Selective encryption for sensitive clips	Planned
v2.8	Menu bar UI	Planned
v2.9	OCR on screenshot clips	Planned
v3.0	MCP Resources	Planned
v3.1	Windows / Linux support	Planned

---

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