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 のバイナリが 1 つだけです。 Node.js も Swift ツールチェーンも、ほかにインストールするアプリも不要です。.mcpb を Claude Desktop にドラッグするだけで完了です。

1 つのプロセス · アイドル時は約 1 mW · RAM は約 24 MB。 一般的なセットアップでは、クリップボードマネージャー、シークレットスキャナー、Obsidian エクスポートを実現するために 3～4 個のバックグラウンドアプリが必要ですが、その構成を置き換えます。

---

これでできること

Claude で作業中に、今日はすでに47 個の項目をコピーしました。URL、JSON スニペット、ダッシュボードからコピーした OpenAI キー、DB ツールからコピーした 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 の DB を読み取り）	✓
クリップの種類を分類（URL／JSON／コード／SQL／シークレット）	✗	✗	✓
コンテキスト検索用にウィンドウタイトルをインデックス化	✗	✗	✓
キャプチャ時にシークレットを検出（gitleaks の 252 個のルール）	✗	✗	✓
Touch ID によるロックを備え、保存時にシークレットを暗号化	✗	✗	✓
スタンドアロンバイナリ（ランタイム不要）	該当なし	✗	✓ macOS + Linux
ワンクリックで .mcpb をインストール	該当なし	✗	✓

GitHub にあるほかの clipboard-mcp リポジトリ約 20 個は、現在のクリップボードを読み取るだけです。履歴をキャプチャするものはありません。

---

インストール

ワンクリック — 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 からリリースクレートを取得し、ローカルでコンパイルします。上記の .mcpb のドラッグ＆ドロップより少し時間がかかります（Apple Silicon でコンパイルに約 2 分）が、Claude Code ユーザーにとって最も手軽な方法です。3 つのコマンドだけでキャプチャを開始できます。

ソースからビルド（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 のポータル処理により、Wayland でクリップボードの読み書きができます。ウィンドウタイトルのキャプチャ（CLIPBOARD_CAPTURE_WINDOW_TITLE=1 でオプトイン）は現在 X11 でのみ動作します。Wayland のサポートは、xdg-desktop-portal のウィンドウタイトル API が広く提供されるようになる v0.4.x まで延期されています。

1Password／Bitwarden： CLIPBOARD_IGNORE_APPS にアプリ名を追加すると、パスワードマネージャーからの貼り付けイベントをスキップできます。

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

Obsidian の Vault への自動ミラーリング（任意）

Obsidian も使用している場合、デーモンはキャプチャしたクリップごとにサイドカー .md を書き込み、日次ノートにタイムラインのエントリーを追加できます。インストール時に設定します。

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

結果：秘密情報以外のすべてのクリップが、フロントマター（kind、source、captured-at）付きで <vault>/clipboard/YYYY-MM/<id>-<kind>-<slug>.md に保存され、サイドカーへのリンクを含む箇条書きが <vault>/daily/YYYY-MM-DD.md に追加されます。秘密情報は決してミラーリングされず、SQLite の Vault で暗号化されたままです。

デーモンは日次ノート内の ## Clipboard captures H2 セクションを管理します。追記のみで、冪等に動作します。その上や下には自由に書き込めます。

---

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 Vault ディレクトリに自動ミラーリングします（クリップごとのサイドカー .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)	1 件の秘密情報を復号します — Touch ID による認証が必要です
get_stats	種類別の件数、最古／最新の項目、DB サイズ
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/)

---

セキュリティモデル

• キャプチャ時に秘密情報を検出 — gitleaks の 252 個以上の正規表現パターン + RFC 7519 JWT + Luhn 検証済みカード。
• 保存時の暗号化 — macOS Keychain に保存された 32 バイトのマスターキーを使用する AES-256-GCM。
• Touch ID による認証 — unlock_secret は LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics) を呼び出します。セッションごとに 5 分間、認証がキャッシュされます。
• デフォルトでは LLM に秘密情報を渡しません — 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-mirror を有効にして測定：

指標	値	測定方法
CPU 定常状態	0.05 %	ps で 60 秒間の累積 CPU 時間の差分を測定（0.03 秒 / 60 秒）
メモリ（RSS）	~24 MB	ps -o rss
平均消費電力	~1 mW	E コア（最大負荷で約 1 W）を継続稼働させた場合の 0.05 %
バッテリーへの影響	3 週間あたり約 1 %	24 時間 365 日の連続稼働を想定。1 mW × 504 時間 = 52 Wh の MacBook Air バッテリーで 0.5 Wh

Chrome のタブ 1 つと比較した様子は、この README の冒頭にある 2 つの正方形の比較をご覧ください。

⌘C を押すたびのバースト時の負荷：約 30 ms の間、CPU 使用率は 1〜3 %（シークレット分類用の正規表現 + FTS5 インデックス + AES-GCM + 任意の Vault ファイル書き込み）。その後アイドル状態に戻ります。アクティビティモニタの エネルギー影響 列は、検出しきい値を下回るため、約 0 と表示されます。

Linux での数値は未検証ですが、同程度と予想されます（arboard によるポーリング + SQLite は移植可能です）。

---

FAQ

Linux／Windows で動作しますか？
Linux：v0.4 以降、動作します（X11 + Wayland のクリップボードに arboard 経由で対応。ウィンドウタイトルの取得は現在 X11 のみ対応）。上記のLinux インストールのセクションをご覧ください。Windows：まだ対応していません。arboard は動作しますが、launchd／systemd 形式のインストーラーがまだ移植されていません。PR を歓迎します。

50 MB のデータをコピーしたらどうなりますか？
現時点ではキャプチャされます。CLIPBOARD_MAX_BYTES による上限設定は今後の予定です。

Claude が私の秘密情報を漏らすことはありますか？
以下の（a）このツールをインストールする、（b）Touch ID を承認する、（c）LLM がログに記録される 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 リリース前のアルファ版です。個人で、まとまった時間を使って開発しています。clipboard-history-mcp が漏えいしたキーを見つけたり、同じ JSON を二度入力する手間を省いたり、ターミナルで Claude を少し便利にしたりした場合は、Patreon で支援者または創設スポンサーになることをご検討ください。

• 月額 $3 — 支援者 ☕ — SUPPORTERS.mdに名前を掲載、Discord ロール
• 月額 $10 — 創設スポンサー 🥇 — この README に名前とアバターを掲載。v1.0 までに参加した場合、永久に掲載されます

スポンサーシップは感謝の気持ちを表すものであり、サポート契約ではありません。優先的な課題のトリアージ、カスタム機能、応答時間 SLA を購入するものではありません。個人開発の OSS では、そのような対応はできません。スポンサーシップによって得られるものは、認知度、時折実施されるロードマップへの投票、そしてこの種のツールを 0.x 以降も保守する価値があるという証明です。

GitHub Sponsors もご利用いただけます。リポジトリ上部のスポンサーボタンをご覧ください。

ライセンス

MIT。vendor/gitleaks.toml は gitleaks のルールカタログ（こちらも MIT）です。vendor/README.mdをご覧ください。