Clipboard History MCP

clipboard-history-mcp

你的剪贴板，Claude 也能读取。按类型分类、加密保护机密内容，原生适配 macOS。

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]

一个 Rust 二进制文件。 无需 Node.js、Swift 工具链或安装其他应用。将 .mcpb 拖到 Claude Desktop 中即可。

一个进程 · 空闲时约 1 mW · 占用约 24 MB 内存。 取代典型配置所需的剪贴板管理器、机密扫描器和 Obsidian 导出工具组合，这些工具通常要用三四个后台应用才能搭建起来。

---

你可以用它做什么

你正在使用 Claude。今天你已经复制了 47 项内容——URL、JSON 代码片段、从控制面板复制的 OpenAI 密钥、从数据库工具复制的 SQL 查询，还有半份 Stripe webhook 负载。现在 Claude 可以使用其中任意一项：

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.

搜索使用 SQLite FTS5 和窗口标题索引——你可以根据复制内容时所在的位置找到剪贴内容，而不仅仅是按内容搜索。

---

为什么其他工具都做不到

	Maccy	maccy-clipboard-mcp	clipboard-history-mcp
捕获剪贴板	✓	（读取 Maccy 的数据库）	✓
分类剪贴内容类型（URL/JSON/代码/SQL/机密内容）	✗	✗	✓
为上下文搜索索引窗口标题	✗	✗	✓
捕获时检测机密内容（252 条 gitleaks 规则）	✗	✗	✓
通过 Touch ID 门控加密静态机密内容	✗	✗	✓
独立二进制文件（无需运行时）	不适用	✗	✓ macOS + Linux
.mcpb 一键安装	不适用	✗	✓

GitHub 上其他约 20 个 clipboard-mcp 仓库都只读取当前剪贴板。没有一个会捕获历史记录。

---

安装

一键安装 — Claude Desktop

1. 从最新版本下载 clipboard-history-mcp.mcpb。
2. 在 Claude Desktop 中依次选择 Settings → Extensions → “Install from file”，然后选取 .mcpb。
3. 重启 Claude Desktop。询问：“列出我最近的剪贴板 URL。”

手动安装 — Claude Code / CLI

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

快速安装 — cargo install

如果你已安装 Rust 工具链（Rust 1.95+）并使用 Claude Code：

cargo install clipboard-history-mcp
clipboard-history-mcp install                      # start daemon
claude mcp add -s user clipboard-history -- clipboard-history-mcp serve

此操作会从 crates.io 拉取发布版 crate 并在本地编译。比上面的 .mcpb 拖放安装稍慢（在 Apple Silicon 上编译约需 2 分钟），但这是 Claude Code 用户最简洁的安装方式——只需运行三条命令即可开始捕获。

从源代码安装（macOS）

要求：Rust 1.95+、macOS 13+。

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 部分支持）

要求：可正常工作的 Secret Service 实现（GNOME Keyring 或 KWallet——大多数桌面安装都包含其中之一）；常规使用无需 xvfb（仅无头 CI 需要）。

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 说明：**通过 arboard 的 portal 处理机制，可以在 Wayland 上读取和写入剪贴板。窗口标题捕获（通过 CLIPBOARD_CAPTURE_WINDOW_TITLE=1 启用）目前仅支持 X11；Wayland 支持将推迟到 v0.4.x，届时 xdg-desktop-portal 的窗口标题 API 将得到广泛支持。

**1Password / Bitwarden：**将应用名称添加到 CLIPBOARD_IGNORE_APPS，即可跳过密码管理器的粘贴事件：

CLIPBOARD_IGNORE_APPS="1Password,Bitwarden,KeePassXC" \
  ./target/release/clipboard-history-mcp install

自动镜像到 Obsidian 知识库（可选）

如果你也使用 Obsidian，守护进程可以为每个捕获的剪贴内容写入一个配套的 .md 文件，并在每日笔记中添加时间线条目。安装时进行配置：

clipboard-history-mcp install --vault ~/Documents/Obsidian/MyVault

结果：每条非机密剪贴内容都会保存为 <vault>/clipboard/YYYY-MM/<id>-<kind>-<slug>.md，并附带前置元数据（kind、source、captured-at）；同时会在 <vault>/daily/YYYY-MM-DD.md 中追加一个指向配套文件的项目符号。机密内容绝不会被镜像——它们会继续加密保存在 SQLite 知识库中。

守护进程拥有每日笔记中的 ## Clipboard captures 二级标题部分——仅追加且具备幂等性。你可以在该部分上方或下方写入其他内容。

---

试着询问 Claude

安装后，将以下任一提示词复制到 Claude 中：

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 会从 15 个可用工具中选出合适的工具并直接作答。

---

配置

在 launchd plist 中设置环境变量（install 会写入这些变量），或通过 claude mcp add --env KEY=val 设置：

变量	默认值	作用
CLIPBOARD_POLL_MS	1500	监视器轮询间隔（ms）
CLIPBOARD_HISTORY_MAX	1000	环形缓冲区大小（仅未固定的剪贴内容——已固定项目不占用环形缓冲区）
CLIPBOARD_CAPTURE_WINDOW_TITLE	0	捕获窗口标题（需要“辅助功能”权限）
CLIPBOARD_IGNORE_APPS	(空)	要跳过的应用显示名称，以逗号分隔
CLIPBOARD_NEVER_STORE_SECRETS	0	偏执模式——仅保留元数据，不保存密文
CLIPBOARD_DATA_DIR	~/Library/Application Support/clipboard-history-mcp	覆盖数据目录
CLIPBOARD_VAULT_PATH	(空)	将非机密剪贴内容自动镜像到此 Obsidian 知识库目录（每条剪贴内容对应一个配套 .md 文件，并在 daily/YYYY-MM-DD.md 中添加项目符号）。安装时通过 --vault PATH 设置。
CLIPBOARD_MAX_BLOB_BYTES	26214400 (25 MB)	跳过大于此值的图像／文件粘贴板。日志会记录一条包含来源应用和大小的 WARN 行。

---

工具（15）

读取

list_history(limit?, kind?, source_app?, since?, pinned_only?)	分页显示历史记录，最新记录在前。pinned_only=true 时仅返回已固定的剪贴内容。
get_item(id)	按 id 获取单条剪贴内容
search_history(query, limit?)	使用 FTS5 BM25 搜索预览文本和窗口标题
get_urls(limit?)	URL 剪贴内容，按主机名去重
get_code(language?, limit?)	代码剪贴内容，可选语言筛选
get_json(limit?)	JSON 剪贴内容及其解析后的结构
get_secrets_index(kind?)	机密元数据——不含值
unlock_secret(id, reason)	解密单条机密——需通过 Touch ID 验证
get_stats	按类型统计数量、最早／最新记录和数据库大小
daemon_status	PID、运行状态

写入

copy_item(id)	将剪贴内容恢复到系统剪贴板
pin_item(id, pinned)	固定剪贴内容，使其不受 clear_history 影响
tag_item(id, tag, remove?)	添加自由格式标签
delete_item(id)	永久删除
clear_history(scope)	'all' | 'older_than_days:N' | 'kind:K'

---

CLI

clipboard-history-mcp daemon         # run watcher (managed by launchd)
clipboard-history-mcp serve          # MCP stdio server (Claude spawns this)
clipboard-history-mcp install [--window-titles]
clipboard-history-mcp uninstall [--keep-data]
clipboard-history-mcp status         # JSON: daemon pid, db size, etc.
clipboard-history-mcp vault list     # secret metadata
clipboard-history-mcp vault unlock N # decrypt secret #N (Touch ID)
clipboard-history-mcp doctor         # diagnose perms/Keychain/pasteboard
clipboard-history-mcp migrate-v2     # validate v0.2.x SQLite (no-op import)
clipboard-history-mcp clean-legacy [-y]  # remove the v0.3.x macOS data dir (~/Library/Application Support/clipboard-history-mcp/)

---

安全模型

• 捕获时检测机密——252 种以上 gitleaks 正则表达式模式 + RFC 7519 JWT + 通过 Luhn 算法校验的银行卡号。
• 静态加密——使用 AES-256-GCM 加密，32 字节主密钥存储在 macOS Keychain 中。
• Touch ID 验证——unlock_secret 会调用 LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)。每个会话的身份验证缓存有效期为 5 分钟。
• 默认不向大模型公开——list_history 和 search_history 会返回机密记录，其中 text: null，preview: "[REDACTED:kind]"。唯一会返回明文的途径是 unlock_secret(id, reason)，且必须提供 reason 参数，并记录在审计日志中。
• 偏执模式——CLIPBOARD_NEVER_STORE_SECRETS=1 仅保留元数据；绝不写入密文。
• 遵循临时类型标记——对于密码管理器（1Password、Bitwarden）通过 org.nspasteboard.ConcealedType 标记的剪贴内容，绝不捕获。

架构

src/
├── main.rs               # binary entry; clap subcommand dispatch
├── core/
│   ├── db.rs             # SQLite WAL + migrations + FTS5
│   ├── store.rs          # add/list/search/delete clips
│   ├── crypto.rs         # AES-256-GCM + Keychain
│   ├── types.rs          # classifier (url/json/sql/shell/code:lang)
│   ├── secrets.rs        # gitleaks rules + JWT + Luhn
│   ├── pasteboard.rs     # NSPasteboard via objc2
│   └── biometry.rs       # LAContext Touch ID gate
├── daemon/{watcher,context}.rs    # poll loop on pinned thread
├── mcp/tools.rs                   # 15 MCP tools via rmcp
└── cli/{install,uninstall,status,vault,doctor,migrate_v2}.rs

技术栈： Rust 1.95 · rmcp 1.6 · tokio · objc2 · rusqlite（内置 FTS5）· aes-gcm · security-framework · objc2-local-authentication · clap 4

---

性能

在 Apple Silicon 上使用默认的 CLIPBOARD_POLL_MS=1500 并启用 vault 镜像时测得的守护进程空闲占用：

指标	数值	测量方法
CPU 稳态占用	0.05 %	通过 ps 测量 60 秒内累计 CPU 时间的变化（0.03 秒 / 60 秒）
内存（RSS）	~24 MB	ps -o rss
平均功耗	~1 mW	持续运行时，一个 E 核（满负荷约为 1 W）的 0.05 %
电池影响	约每 3 周 1 %	1 mW × 504 小时 = 52 Wh 的 MacBook Air 电池消耗 0.5 Wh，假设持续运行 24/7

请参阅本 README 顶部的双方块对比图，直观了解与单个 Chrome 标签页相比的情况。

每次按下 ⌘C 的突发开销：在 1–3 % CPU 占用下运行约 30 毫秒（机密分类器正则表达式 + FTS5 索引 + AES-GCM + 可选的 vault 文件写入），随后恢复空闲。活动监视器的 能源影响 列显示约为 0，低于其检测阈值。

Linux 的数据尚未测试，但预计量级相近（arboard 轮询 + SQLite 可移植）。

---

常见问题

这能在 Linux/Windows 上运行吗？
Linux：可以，从 v0.4 起支持（通过 arboard 支持 X11 + Wayland 剪贴板；目前仅支持捕获 X11 窗口标题）。请参阅上文的 Linux 安装部分。Windows：暂不支持——arboard 在 Windows 上可用，但尚未移植 launchd/systemd 风格的安装程序。欢迎提交 PR。

如果我复制了一个 50MB 的数据块，会怎样？
目前会被捕获。限制 CLIPBOARD_MAX_BYTES 已列入路线图。

Claude 会泄露我的机密吗？
除非你 (a) 安装此工具，(b) 批准 Touch ID，(c) 大模型选择使用会记录日志的 reason 调用 unlock_secret，否则不会。list_history/search_history 中机密条目的 text 字段始终为 null。

它能在多台 Mac 之间同步吗？
不支持原生跨设备同步——SQLite vault 保留在本地。如果将 --vault PATH 指向同步中的 Obsidian vault（iCloud、git、Syncthing 等），每个剪贴内容的侧边 Markdown 文件会随之同步；但机密永远不会镜像到 vault，因此受密码保护的项目仍保留在原始设备上。

我可以在 Maccy 已经运行时使用它吗？
可以。两者不会冲突——Maccy 提供 UI，本工具提供 MCP 层。两者会各自独立轮询 NSPasteboard.changeCount。

其他剪贴板管理器呢？
答案相同——没有独占锁。最坏的情况是两者存储相同的剪贴内容；存储开销微不足道。

---

更新日志

请参阅 CHANGELOG.md。最新版本：v0.3.0-alpha.0。

贡献

请参阅 CONTRIBUTING.md。欢迎提交 PR——尤其欢迎提供 macOS 13/14 问题的复现步骤。

赞助

1.0 之前的 alpha 版本。由个人利用空闲时间陆续构建。如果 clipboard-history-mcp 帮你发现了泄露的密钥、让你免于重复输入相同的 JSON，或只是让 Claude 在你的终端中稍微更有用——欢迎考虑成为 Patreon 支持者或创始赞助人。

• 每月 $3 — 支持者 ☕ — 姓名列入 SUPPORTERS.md，获得 Discord 身份组
• 每月 $10 — 创始赞助人 🥇 — 姓名 + 头像显示在此 README 中；若在 v1.0 发布前加入，将永久列出

赞助是表达感谢，并非支持合同。赞助不会获得优先处理问题、自定义功能或响应时间 SLA——个人维护的 OSS 无法以这种方式扩展。赞助能带来的是曝光机会、偶尔参与路线图投票，以及证明这类工具值得在 0.x 之后继续维护。

也可以通过 GitHub Sponsors 赞助——请查看仓库顶部的 Sponsor 按钮。

许可证

MIT。vendor/gitleaks.toml 是 gitleaks 规则目录（同样采用 MIT 许可证）——请参阅 vendor/README.md。