clipboard-mcp-server

---

概要

macOS、Linux（X11/Wayland）、Windows のシステムクリップボードに対応しています。任意の MCP クライアントから、テキスト、HTML、RTF、画像の内容を読み取り、書き込み、確認できます。stdio プロセスまたはローカルの Streamable HTTP サーバーとして動作します。

ツール

ツール	説明
clipboard_read	指定した形式（テキスト、HTML、RTF、画像、または最もリッチな形式の自動選択）でクリップボードの内容を読み取ります
clipboard_write	プレーンテキストまたは HTML をクリップボードに書き込み、現在の内容を置き換えるか、クリップボードを完全に消去します
clipboard_inspect	内容全体を読み取らずに、利用可能なクリップボード形式とバイトサイズを一覧表示します

---

機能リファレンス

clipboard_read _ツール

• text、html、rtf、image を読み取ります。auto を指定すると、存在する形式のうち最もリッチな形式を選択します（image > html > rtf > text）。一括読み取りの上限は、テキスト／HTML／RTF が 512 KB、画像が 5 MB です
• format、content、バイトサイズ、complete、representationId を返します。画像は base64 PNG で、任意の width／height を含みます。失敗時には format_unavailable、content_too_large、representation_changed、clipboard_unavailable、inspect_unreadable が返されます
• 大きな値を扱う場合は、バイト単位の offset／limit（最小値は 4、上限は形式ごとに異なります）を使用し、完了するまで各 nextOffset を representationId とともに offset として渡してください。画像のスライスはバイトチャンクです。各チャンクを個別にデコードして順番に連結してください。画像ブロックが添付されるのは、画像全体を読み取った場合のみです

---

clipboard_write _ツール

• 空でないcontentまたはclear: trueのいずれか一方を指定してください。formatはtextまたはhtmlを受け付け、書き込み上限は1 MBです。HTMLには、macOS／Windowsではタグを除去したプレーンテキストのフォールバックが付きます。Linuxでは、プレーンテキストへの貼り付けでマークアップが含まれる場合があります。
• format／byteSizeを返します。クリア時は、バイト数がゼロでcleared: trueを返します。オプションのpreviousContentには、512 KBの読み取り上限内で以前のプレーンテキストが格納されます。失敗時にはcontent_too_largeまたはclipboard_unavailableが付与されます。X11でのクリアにはxselが必要です。
• CLIPBOARD_READ_ONLYを設定すると、ツールがtools/listから削除され、書き込みとクリアの両方が無効になります。

---

clipboard_inspect _ツール

• 読み取り形式を選ぶために、primaryFormat（image > html > rtf > text、またはempty）とavailableFormatsを返します。
• rawTypesには、プラットフォームの識別子と測定したbytesが一覧表示されます。読み取りできない場合はmeasurementFailedが表示されます。失敗時にはinspect_unreadableまたはclipboard_unavailableが付与されます。

---

機能

@cyanheads/mcp-ts-coreを基盤としており、stdioおよびStreamable HTTPトランスポート、プラグイン可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションのOpenTelemetryトレースを備えた構造化ログに対応しています。

クリップボード固有の機能：

• 起動時にクロスプラットフォームのバックエンドを検出します。macOS（osascript/JXA）、Linux X11（xclip）、Linux Wayland（wl-clipboard）、Windows（PowerShell 5.1+）に対応しています。
• セマンティックな形式マッピングにより、プラットフォーム固有の型識別子（UTI、TARGETS、Windowsの形式名）を、すべてのバックエンドでtext、html、rtf、imageに対応付けます。
• プラットフォームに応じたHTML書き込みに対応しています。macOSとWindowsではHTMLと、タグを除去したプレーンテキストのフォールバックを公開します。LinuxではHTMLのみがペイロードとなり、プレーンテキストの貼り付け先でも受け取れます。
• 画像に対応しています。すべてのバックエンドが、幅と高さを含むPNGをBase64で返します（LinuxのバックエンドではPNGヘッダーから幅と高さを読み取ります）。

エージェントに適した出力：

• サイズ制限付きのI/Oにより、形式の上限を超える読み取りと書き込みは、黙って切り詰められるのではなく、バイト数と上限のメタデータを含む型付きエラーcontent_too_largeで失敗します。
• 範囲指定での継続に対応しています。clipboard_readは、オーバーサイズのコンテンツをoffset／limitで分割し、nextOffsetを返すため、すべてを一度に読み取る必要はありません。また、representationIdにより、分割読み取りの途中でクリップボードが変更された場合は明確に失敗し、異なる値が連結されるのを防ぎます。
• 元に戻す機能に対応しています。clipboard_writeはpreviousContentを返すため、意図しない上書きを元に戻せます。
• 失敗の種類を区別します。format_unavailable、content_too_large、representation_changed、inspect_unreadable、clipboard_unavailableは、汎用エラーではなく、復旧のヒントを含む型付きの理由です。各バックエンドが独自にヘルパーの結果を分類するため（wl-clipboardとxclipのリリース表記の違いにも対応）、空のクリップボード、存在しない形式、到達不能なヘルパーが混同されることはありません。

---

はじめに

以下をMCPクライアントの設定ファイルに追加してください。

{
  "mcpServers": {
    "clipboard-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/clipboard-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Bunが不要なnpxを使う場合：

{
  "mcpServers": {
    "clipboard-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/clipboard-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Streamable HTTPの場合は、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

Bun 1.4.0+またはNode.js 24+。

**macOS：**追加のツールは不要です。osascriptは標準で付属しています。

Linux X11：xclipをインストールする必要があります。clipboard_writeのclearモードには、さらにxselが必要です。空の選択を所有するのではなく、選択を別の場所に引き渡せるのは、この2つのうちxselだけです。

apt install xclip xsel      # Debian/Ubuntu
pacman -S xclip xsel        # Arch

Linux Wayland：wl-clipboardをインストールする必要があります。

apt install wl-clipboard    # Debian/Ubuntu
pacman -S wl-clipboard      # Arch

**Windows：**PowerShell 5.1+（Windows 10以降に標準で付属）。

---

設定

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_HOST	HTTP サーバーのホスト名。	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	HTTP サーバーのエンドポイントパス。	/mcp
MCP_HTTP_MAX_BODY_BYTES	受信する JSON-RPC リクエスト本文の最大バイト数です。フルサイズの clipboard_write が JSON エスケープ後も収まるよう、フレームワークのデフォルト値 1 MiB より大きく設定されています（最悪の場合、ソースの 1 バイトにつきワイヤー上で 6 バイト必要です）。0 にするとガードが無効になり、リバースプロキシに委ねられます。	7340032
MCP_SESSION_MODE	HTTP セッションモード：auto、stateful、または stateless。auto は stateful に解決されます。このサーバーのデフォルトは stateless で、セッションごとの状態を保持しません。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、notice、warning、error）。	info
LOG_TOOL_FAILURE_PAYLOADS	失敗したツールの引数と結果を、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（16384）を上限としてログに記録します。キー名に基づいて機密情報をマスキングします。クリップボードの内容に含まれるシークレットはマスキングされません。	false
OTEL_ENABLED	OpenTelemetry インストルメンテーションを有効にします。	false
CLIPBOARD_READ_ONLY	クリップボードを読み取り専用で提供します。true の場合、clipboard_write はマニフェストおよび tools/list に含まれず、呼び出しもできませんが、ランディングページと起動ログには無効として表示されます。true/false/1/0/yes/no/on/off を受け付けます。認識できない値の場合、起動に失敗します。	false

任意のオーバーライドの全一覧は .env.example を参照してください。

---

サーバーの実行

ローカル開発

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

チェックとテスト

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest test suite

---

プロジェクト構成

パス	用途
src/index.ts	エントリーポイント — createApp() を介してツールを登録します
src/mcp-server/tools/definitions/	ツール定義：clipboard_read、clipboard_write、clipboard_inspect
src/services/clipboard/	プラットフォームのバックエンド（macOS、Linux X11、Wayland、Windows）とサービスファサード
tests/	ツールとバックエンドの Vitest テスト
framework-skills/	エージェントのワークフロースキル（add-tool、field-test、polish-docs-meta など）

---

開発ガイド

開発者向けプロトコルの全容（ツールのパターン、サービスのパターン、エラー処理、ログの規約、変更をリリースするためのチェックリスト）については、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで例外を捕捉するのは、バックエンドの型付き結果に応じて処理する場合のみです。宣言済みのエラー理由にマッピングするか、次のフォーマットへ auto を進めます
• リクエストスコープのログ記録には ctx.log を使用します
• Docker は使用しません — このサーバーはホスト OS への直接アクセスが必要です（JXA/NSPasteboard、xclip、wl-clipboard、PowerShell）。これらはコンテナー内では動作しません

---

コントリビューション

github.com/cyanheads/clipboard-mcp-server で Issue を受け付けています。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

---

ライセンス

Apache 2.0 — LICENSE を参照してください。