Your clipboard, but Claude can read it. Type-classified, secret-encrypted. macOS + Linux.
io.github.d-khomenko/clipboard-history-mcp MCP Server
This MCP server provides clipboard history on macOS and Linux, enabling Claude access to clipboard content. It supports type-classified, secret-encrypted storage, with a Rust daemon managed via launchd. Clips are stored in SQLite with FTS5, and non-secret clips can be sent to an Obsidian vault.
🛠️ Key Features
Type-classified clipboard history
Secret-encrypted clipboard storage
Rust daemon, launchd-managed
SQLite + FTS5 for storage and search
macOS-native support; also supports Linux
🚀 Use Cases
Capturing and retaining clipboard content for later reference
Allowing Claude to read clipboard entries
Storing searchable clipboard history (via FTS5)
Optionally routing non-secret clips to an Obsidian vault
⚡ Developer Benefits
Uses SQLite with FTS5, suitable for text search over history
Structured pipeline: classify + encrypt, then store
⚠️ Limitations
Described as macOS-native and also macOS + Linux; other platforms are not mentioned
Your clipboard, but Claude can read it. Type-classified, secret-encrypted, macOS-native.
flowchart LR
U[You ⌘C something] --> D[Rust daemon<br/>launchd-managed]
D -->|classify + encrypt| DB[(SQLite + FTS5)]
D -. non-secret clips .-> O[Obsidian vault<br/>optional]
C[Claude] -->|MCP stdio| M[15 tools]
M --> DB
M -->|Touch ID| V[Vault<br/>AES-256-GCM]
One Rust binary. No Node.js, no Swift toolchain, no other apps to install. Drag a .mcpb into Claude Desktop, done.
One process · ~1 mW idle · ~24 MB RAM. Replaces the clipboard-manager + secret-scanner + Obsidian-export stack a typical setup needs three or four background apps to assemble.
Demo: copy a URL, a JSON snippet, code, an OpenAI key — daemon classifies each, then Claude lists them in chat and unlocks the secret behind Touch ID.
What this gets you
You're working in Claude. You've copied 47 things today — URLs, JSON snippets, an OpenAI key from a dashboard, a SQL query from your DB tool, half a Stripe webhook payload. Now Claude can use any of them:
code
You: "Find that API key I copied from the OpenAI dashboard yesterday"
Claude: Found 1 secret matching "OpenAI" — kind: openai_api_key,
source: Safari, copied 14h ago. Last 4 chars: ab12.
To reveal, call unlock_secret(id=23, reason="...").
You: "Give me all the GitHub URLs I copied"
Claude: Returns 12 unique GitHub URLs deduplicated by repo,
ranked by how often you pasted them back.
You: "There was a Stripe JSON config in the buffer — restore it to my clipboard"
Claude: Found, restoring. ✓ ready to ⌘V.
You: "What code did I copy from ChatGPT over the last 2 hours?"
Claude: 3 Python snippets, 1 SQL query, 1 shell command.
You: "Show me the screenshot I just copied"
Claude: Returns a 142×120 PNG, mime image/png, captured from Preview 2 minutes ago.
Search uses SQLite FTS5 + window-title indexing — you find clips by where you copied them, not just by content.
The other ~20 clipboard-mcp repos on GitHub only read the current clipboard. None capture history.
Install
One-click — Claude Desktop
Download clipboard-history-mcp.mcpb from the latest release.
Claude Desktop → Settings → Extensions → "Install from file" → pick the .mcpb.
Restart Claude Desktop. Ask: "List my recent clipboard URLs."
Manual — Claude Code / CLI
bash
curl -L https://github.com/d-khomenko/clipboard-history-mcp/releases/latest/download/clipboard-history-mcp.mcpb \
-o clipboard-history-mcp.mcpb
unzip clipboard-history-mcp.mcpb -d ext
# register MCP
claude mcp add -s user clipboard-history -- ./ext/server/clipboard-history-mcp serve
# install background daemon (captures even when Claude is closed)
./ext/server/clipboard-history-mcp install
Quick install — cargo install
If you have a Rust toolchain (Rust 1.95+) and use Claude Code:
bash
cargo install clipboard-history-mcp
clipboard-history-mcp install # start daemon
claude mcp add -s user clipboard-history -- clipboard-history-mcp serve
This pulls a release crate from crates.io and compiles locally. Slightly slower than the .mcpb drag-and-drop above (compile takes ~2 min on Apple Silicon), but it's the cleanest path for Claude Code users — three commands and you're capturing.
From source (macOS)
Requirements: Rust 1.95+, macOS 13+.
bash
git clone https://github.com/d-khomenko/clipboard-history-mcp
cd clipboard-history-mcp
cargo build --release
./target/release/clipboard-history-mcp install # start daemon
claude mcp add -s user clipboard-history -- "$(pwd)/target/release/clipboard-history-mcp" serve
Linux (X11; Wayland partial)
Requirements: a working Secret Service implementation (GNOME Keyring or KWallet — comes with most desktop installs), xvfb not required for normal use (only for headless CI).
bash
git clone https://github.com/d-khomenko/clipboard-history-mcp
cd clipboard-history-mcp
cargo build --release
# Set a master password (used to wrap your AES master key)
./target/release/clipboard-history-mcp migrate-v2
# Install systemd user service
./target/release/clipboard-history-mcp install
# Optional: keep daemon running after logout
./target/release/clipboard-history-mcp install --linger
# Register with Claude Code
claude mcp add -s user clipboard-history -- "$(pwd)/target/release/clipboard-history-mcp" serve
Wayland note: clipboard read/write works on Wayland via arboard's portal handling. Window-title capture (opt-in via CLIPBOARD_CAPTURE_WINDOW_TITLE=1) currently only works on X11; Wayland support is deferred to v0.4.x once xdg-desktop-portal window-title APIs are widely shipped.
1Password / Bitwarden: add app names to CLIPBOARD_IGNORE_APPS so password-manager paste events are skipped:
Result: every non-secret clip lands as <vault>/clipboard/YYYY-MM/<id>-<kind>-<slug>.md with frontmatter (kind, source, captured-at), and a bullet appended to <vault>/daily/YYYY-MM-DD.md linking back to the sidecar. Secrets are never mirrored — they stay encrypted in the SQLite vault.
The daemon owns the ## Clipboard captures H2 section in your daily notes — append-only, idempotent. You can write anything else above or below it.
Try asking Claude
Copy any of these prompts into Claude after install:
code
List my last 20 clipboard entries.
Show me only the URLs I've copied today.
Search my clipboard history for "anthropic".
Find any code snippets in Python from the last 3 hours.
How many secrets are in my clipboard vault, by kind?
Pin the JSON I just copied — I'll need it again.
Show me only my pinned clips.
What apps did I copy from most this week?
Restore that GitHub PR link to my clipboard.
Claude picks the right tool from 15 available and answers directly.
Configuration
Set env vars in the launchd plist (install writes them) or via claude mcp add --env KEY=val:
Variable
Default
What it does
CLIPBOARD_POLL_MS
1500
Watcher poll interval (ms)
CLIPBOARD_HISTORY_MAX
1000
Ring-buffer size (unpinned clips only — pinned items sit outside the ring buffer)
Auto-mirror non-secret clips to this Obsidian vault directory (sidecar .md per clip + bullet in daily/YYYY-MM-DD.md). Set via --vault PATH at install time.
CLIPBOARD_MAX_BLOB_BYTES
26214400 (25 MB)
Skip image / file pasteboards larger than this. Logs a WARN line with the source app + size.
Encryption at rest — AES-256-GCM with a 32-byte master key in macOS Keychain.
Touch ID gate — unlock_secret calls LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics). 5-minute auth cache per session.
LLM-blind by default — list_history and search_history return secret rows with text: null and preview: "[REDACTED:kind]". The only path that returns plaintext is unlock_secret(id, reason), and the reason argument is mandatory and audit-logged.
Paranoid mode — CLIPBOARD_NEVER_STORE_SECRETS=1 keeps metadata only; ciphertext never written.
Transient-type respect — clips marked by password managers (1Password, Bitwarden) with org.nspasteboard.ConcealedType are never captured.
Burst cost on each ⌘C: ~30 ms tick at 1–3 % CPU (secret-classifier regexes + FTS5 index + AES-GCM + optional vault file write), then back to idle. Activity Monitor's Energy Impact column reports ~0 — below its detection threshold.
Linux numbers untested but expected similar order of magnitude (arboard polling + SQLite is portable).
FAQ
Does this run on Linux/Windows?
Linux: yes since v0.4 (X11 + Wayland clipboard via arboard; window-title capture is X11-only for now). See the Linux install section above. Windows: not yet — arboard works there, but the launchd/systemd-style installer hasn't been ported. PRs welcome.
What if I copy a 50MB blob?
Currently captured. A CLIPBOARD_MAX_BYTES guard is on the roadmap.
Can Claude leak my secrets?
Not without you (a) installing this tool, (b) approving Touch ID, (c) the LLM choosing to call unlock_secret with a reason that gets logged. The text field for secret rows is always null in list_history/search_history.
Does it sync across Macs?
No native cross-device sync — the SQLite vault stays local. If you set --vault PATH to point inside a synced Obsidian vault (iCloud, git, Syncthing, etc.), the per-clip sidecar markdown files follow your sync — but secrets are never mirrored to the vault, so password-protected items remain on the originating machine.
Can I use this with Maccy already running?
Yes. They don't conflict — Maccy provides UI, this provides the MCP layer. Both poll NSPasteboard.changeCount independently.
What about [other clipboard manager]?
Same answer — there's no exclusive lock. Worst case, both store the same clip; storage cost is trivial.
See CONTRIBUTING.md. PRs welcome — issues with macOS 13/14 reproductions especially.
Sponsor
Pre-1.0 alpha. Built solo, in bursts. If clipboard-history-mcp finds you a
leaked key, saves you from typing the same JSON twice, or just makes Claude
slightly more useful at your terminal — consider becoming a backer or
Founding Sponsor on Patreon.
$3 / month — backer ☕ — name in SUPPORTERS.md, Discord role
$10 / month — founding sponsor 🥇 — name + avatar in this README, permanently listed if you join before v1.0
Sponsorship is gratitude, not a support contract. It does not buy priority
issue triage, custom features, or response-time SLA — solo OSS doesn't scale
that way. What it buys: visibility, the occasional roadmap vote, and proof
that this kind of tool is worth maintaining past 0.x.
GitHub Sponsors works too — see the Sponsor button at the top of the repo.
License
MIT. vendor/gitleaks.toml is the gitleaks rule catalog (also MIT) — see vendor/README.md.
Install
Configuration
Environment variables
CLIPBOARD_VAULT_PATH
Auto-mirror non-secret clips to this Obsidian vault directory. Sidecar `.md` per clip + bullet in `daily/YYYY-MM-DD.md`. Secrets are never mirrored.
CLIPBOARD_CAPTURE_WINDOW_TITLE
Set to '1' to capture the active window title alongside each clip (needs Accessibility permission on macOS, X11 only on Linux).
CLIPBOARD_IGNORE_APPS
Comma-separated app display names to skip (e.g. '1Password,Bitwarden,KeePassXC').
CLIPBOARD_NEVER_STORE_SECRETS
Set to '1' for paranoid mode — secrets are detected and metadata-logged but ciphertext is never stored.
CLIPBOARD_HISTORY_MAX
Maximum number of clips kept in the ring buffer. Defaults to 1000.
CLIPBOARD_POLL_MS
Watcher poll interval in milliseconds. Defaults to 1500.
