clawtouch-mcp

English | 简体中文

clawtouch-mcp

AI エージェントに本物の手を与えましょう。 MCP サーバーです。MCP 互換クライアントならどれでも — Claude Desktop、 Cline、Continue、 Cursor、OpenClaw、 Hermes Agent など — USB HID デバイスを介して実際のマウスを動かし、本物のキーを押せるようにします。

---

これは何ですか？

stdio 経由で Model Context Protocol（MCP）を話し、マウス／キーボードの基本操作 — hid.click、hid.type、 hid.scroll、キーの組み合わせ、hid.screenshot — を、すでにお使いの任意の AI エージェントに提供する、スタンドアロンの Python プロセスです。内部では、USB シリアル経由で ClawTouch HID デバイス（オープンソースの ClawTouch HID ファームウェアを実行する Raspberry Pi Pico 2、またはすぐに使える ClawTouch ボックス）と通信し、各ツール呼び出しを実際の USB HID レポートに変換します。ターゲット OS は物理キーボードとマウスそのものとして認識します。入力は、ソフトウェアで注入された合成イベントではなく、接続した周辺機器と同じドライバーパスを通じて届きます。

📦 MIT ライセンスです。ClawTouch バックエンドも、LLM も、その上に重ねるエージェントループもありません。 他のエージェントスタックが実機と通信するための、HID の基本機能だけを提供します。

⚠️ これにより、エージェントはマシンに対して本物のキーボード／マウス操作権限を持ちます。 これは、キーボードの前にいる人と同じ操作権限です。まず安全性をお読みください。

ハードウェア HID を使う理由

ソフトウェアによる自動化（PyAutoGUI、OS レベルの入力 API、画面上の位置をクリックするマルチモーダルモデル）は、セッションに合成入力イベントを注入します。そのため、対象マシン上のそのユーザーセッションで、フォーカスを得たエージェントプロセスが実行されている必要があります。USB HID 周辺機器はその逆です。標準の OS HID ドライバースタックを通って、接続されたキーボードやマウスとまったく同じ実際の HID レポートを送信します。OS は Pico を標準の USB HID クラスデバイスとしてネイティブに認識するため、対象側の入力にはマウス／キーボードのドライバーも HID エージェントプロセスも不要です。この違いこそがこのプロジェクトの要点であり、以下のほかのセクションはすべてこれを基盤としています。

ボードは、接続されているマシンを操作します。 コマンドは入力に使うのと同じ USB ケーブル経由で受信するため、clawtouch-mcp もそのマシン上で実行されます。入力側にドライバーは引き続き不要です。エージェント自体は別の場所で実行できます。デプロイ方法を参照してください。

適した用途：

• キオスク／ロックダウンされたマシン — インストールや常時実行が必要な入力ドライバーや入力エージェントは不要です。ボードは標準の USB キーボードとマウスとして動作します（clawtouch-mcp 自体はそのマシン上で実行します）。
• アクセシビリティ — アプリごとの合成入力の互換性に悩まされることなく、エージェントが HID コマンドを発行してユーザー自身のコンピューターを操作できるようにします。
• 互換性テスト — 合成イベントの注入とは異なる場合がある、外部からの HID 入力をソフトウェアが正しく処理できるか検証します。
• テスト環境 — 開発用ノート PC 上のエージェントから、clawtouch-mcp を実行しているテストマシンを操作します（たとえば SSH 経由で起動します。デプロイ方法を参照）。

適さない用途：

• 大量のアカウント作成／複数アカウントの操作 — 1 台のホストに接続する周辺機器は構造的に不向きです。1 台のデバイスが操作できる対象はちょうど 1 台であり、10 台のマシンを操作するにはデバイスを 10 台購入する必要があります。
• アプリケーション固有のスクリプト化されたショートカット（セレクター、特定のサイトやアプリ向けの固定フロースクリプト）。これらは、このプリミティブなレイヤー自体ではなく、その上に構築されるエージェント／RPA フレームワークで扱うものです。

標準的なデスクトップアプリ（ブラウザー、IDE、オフィススイート）では、ソフトウェアのみの方法で十分です。その場合、ハードウェアは追加の選択肢であり、必須ではありません。代替できない価値があるのは、対象側に入力ドライバーや入力エージェントを用意せず、本物の物理 HID デバイスとして入力を届ける必要がある上記のようなケースです。「適さない用途」のコンプライアンス上の境界については、適切な使用を参照してください。

クイックスタート

⚠️ 始める前に、安全性をお読みください。接続されたエージェントは、キーボードを操作する人間と同じようにこのマシンを操作できます。

インストール

pip install clawtouch-mcp                     # minimal (serial only)
pip install 'clawtouch-mcp[screenshot]'       # + mss + Pillow (JPEG, Retina resize)
pip install 'clawtouch-mcp[screenshot-min]'   # mss only — no native deps, works
                                              # under hardened-runtime hosts
pip install 'clawtouch-mcp[window]'          # pyobjc — macOS needs it for
                                              # screen.windows; no-op elsewhere

プラットフォーム別セットアップガイド（初回インストール時に推奨）：

• Windows — docs/windows-setup.md：デュアル COM ポートの列挙、VS Code Claude 拡張機能の .mcp.json 設定、ウィンドウ全体の再起動が必要なこと、ディスプレイのスケーリングに関する注意事項。
• macOS — docs/macos-setup.md：初回接続時に表示されるキーボード設定アシスタントのダイアログ、デュアル USB-CDC ポート、画面収録のアクセス許可、Pinyin IME の句読点に関する注意点。

実行

# 1. Auto-detect HID board AND auto-detect screen size (v0.2.3+)
clawtouch-mcp

# 2. Explicit port (Windows), screen still auto-detected
clawtouch-mcp --port COM7

# 3. Pin screen size manually (e.g. clamp to one monitor in a multi-monitor setup)
clawtouch-mcp --screen 1920x1080

# 4. No hardware — everything is logged, nothing moves (dev/CI mode)
clawtouch-mcp --mock --log-level INFO

v0.2.3 以降では、起動時にメインモニターの物理ピクセルサイズを自動検出するため、座標はハードコードされた 1920x1080 ではなく実際の画面サイズに合わせて制限されます。MCP クライアントから device.info を使って検出結果を確認してください（screen.source は "detected"／"explicit"／"unset" のいずれかです）。

Claude Desktop での使用

~/Library/Application Support/Claude/claude_desktop_config.json （macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します：

{
  "mcpServers": {
    "clawtouch": {
      "command": "clawtouch-mcp",
      "args": ["--port", "COM7", "--screen", "1920x1080"]
    }
  }
}

Claude Desktop を再起動します。MCP サーバーの一覧に clawtouch が表示され、16 個のツール（HID 14 個＋デバイス 2 個）が利用可能になります（--allow-screenshot を渡すと、hid.screenshot と screen.windows が有効になり、さらに 2 個追加されます）。次のように試してみてください：

画面のスクリーンショットを撮り、検索ボックスを見つけてクリックし、 「hello world」と入力してください。

（hid.screenshot ツールを有効にするには --allow-screenshot が必要です。プライバシー保護のため、デフォルトでは無効です。）

その他の MCP クライアント

検証済みの 7 つのクライアント（Claude Desktop / Code、 Cursor、OpenClaw、Hermes Agent、ChatGPT Desktop / Codex CLI、 Cherry Studio、Trae IDE）でコピーして貼り付けられる設定については、 examples/integrations/INTEGRATIONS.md をご覧ください。 新しいクライアントを追加する PR も歓迎します。

デプロイモード

エージェントは画面と同じマシン上で動作していますか？ clawtouch-mcp が担うのは 入力側（エージェントのツール呼び出し → HID レポート → 実際の入力）と、オプトインで有効にできる、実行中のマシンの hid.screenshot です。画面をどう扱うか — 画面を読み取り、次に何をするか判断すること — は、このリポジトリの対象外です。

ローカルモード — 一般的なケースです。 エージェント、clawtouch-mcp、Pico、操作対象の画面がすべて 1 台の PC 上にあります。hid.screenshot は同じ画面をキャプチャするため、視覚的なフィードバックループが自然に完結します。Pico は標準的な USB HID デバイスで、ドライバーは不要です。アクセシビリティ、1 台のマシンでの RPA、互換性テスト、マシン内でのキオスクのセルフサービスに適しています。

別のマシン上のエージェント。 ボードは USB CDC データチャネル（キーボードとマウスのデータも送るのと同じケーブル）経由でコマンドを受け取るため、接続先のマシンで常に動作し、clawtouch-mcp もそこで実行されます。エージェントは別の場所で実行してもかまいません。MCP クライアントに、対応している任意のトランスポート（たとえば SSH コマンド）経由で、対象マシン上の clawtouch-mcp を起動させます。キー入力、テキスト入力、相対マウス移動はローカルの場合と同様に動作します。一方、絶対位置でのクリックと移動ではカーソル位置を読み取り、hid.screenshot では画面を読み取るため、これらを使うには、サーバーをログイン済みデスクトップセッション内で実行する必要があります。通常の SSH ログインではそうなっていないことがよくあります。Linux では、デスクトップの X サーバー用に DISPLAY（および XAUTHORITY）を設定します。Windows では、OpenSSH セッションは対話型デスクトップの外部で実行されるため、代わりにセッション内からサーバーを起動します。macOS では、画面収録を許可すれば動作します（macOS のセットアップを参照）。このファームウェアが提供しないのは、何も実行していないマシンを操作する方法です。それにはボードへの第 2 のコマンド経路が必要ですが、このリポジトリの対象外です。

安全性

自律型エージェントを接続する前に、これをお読みください。上記の実行時制限は 洪水入力やタイプミスを防ぐためのものであり、誤動作するエージェントに対する セキュリティ境界ではありません。

実行時の安全制限

• 座標は --screen WxH の範囲内に制限されるため、エージェントがマウスを不正なピクセル位置に移動することはできません。
• 入力するテキストは、1 回の呼び出しにつき最大 4096 文字です。
• hid.type はASCII／US キーボードレイアウトのテキスト用です。エージェントが複数行の下書きを誤って送信しないよう、制御文字（改行／タブなど）はデフォルトで除去されます。Enter は hid.key("enter")、Tab は hid.key("tab") で送信してください。ASCII 以外の文字（CJK、絵文字、曲線引用符など）を含むテキストは、一切入力される前に拒否されます。そうしないと、ファームウェアが該当文字の最初の位置で停止し、テキストが途中まで入力された状態になってしまいます。そのようなテキストはクリップボードに入れて、代わりに貼り付けてください。
• すべての操作は --ops-per-sec（デフォルトは 20）にレート制限されます。これは個々の HID レポートではなく、ツール呼び出しの数を数えます。hid.drag や長い hid.type のような 1 回の呼び出しでも多数のレポートが出力されるため、実効的な HID レポートレートはこれより高くなります。これは連打や誤入力を防ぐためのものであり、セキュリティ上のスロットルではありません。
• hid.screenshot は --allow-screenshot を指定しない限り無効です。
• エージェントからパニックストップ用ツールとして使えるよう、hid.release_all が公開されています。

これに接続されたエージェントができること

clawtouch-mcp は、エージェントのツール呼び出しを実際の USB HID 入力に変換します。正当なユースケース（キオスク、アクセシビリティ、互換性テスト、テスト環境）を実現するこの特性には、同じだけのリスクも伴います。

ここに接続された自律型エージェントは、実質的に、キーボードの前に座る人と同じ範囲でホストを操作できます。 あらゆるアプリケーションを開き、ターミナルでコマンドを実行し、ソフトウェアをインストールまたは削除し、ファイルを読み取り、移動、削除できます。入力は通常の HID として届くため、確認プロンプトだけでは信頼できる防壁になりません。あらゆる同意ダイアログに対して、エージェントが操作する可能性があるものとして対応してください。clawtouch-mcp は意図や内容を検査しません。各呼び出しを忠実にハードウェアへ転送します。

これは、エージェントが何をするかを決めるため、意図しないまま発生することがあります。主なきっかけは次のとおりです。

• プロンプトインジェクション。 エージェントが画面、ウェブページ、画像から読み取る信頼できないテキストに、指示を上書きする内容が含まれていることがあります。
• モデルの誤り。 モデルがタスクを誤解し、間違ったウィンドウ、ファイル、ボタンを操作することがあります。
• 自律性の範囲が広すぎること。 タスクの自由度が高く、チェックポイントが少ないほど、被害が及ぶ範囲は大きくなります。

これは意図しない障害モードであり、サポート対象の使用方法ではありません。HID 入力を意図的に使ってシステムのセキュリティ制御を回避することは、以下の許容される使用方法の範囲外です。また、SECURITY.md に記載されているソフトウェアのバグとは別のものです。そこに挙げられた問題は、いずれもエージェントがユーザー自身の意図に反して行動するケースを扱っていません。MIT ライセンスの「現状有姿／保証なし」条項は責任を免除するためのものであり、リスクを理解したうえでの利用を促す通知ではありません。自律型エージェントを安全に実行する責任は、導入者であるユーザーにあります。この通知は情報提供のみを目的としています。MIT ライセンスを変更、限定、拡張するものでも、保証または注意義務を生じさせるものでも、Tinqiao に責任を転嫁するものでもありません。MIT ライセンスの無保証／責任免除条項は、引き続き全面的に適用されます。

オペレーターによるリスク軽減策

HID 入力を操作するエージェントは、有能ではあるものの完全には信頼できないオペレーターに、マシンを実際に操作させるようなものとして扱ってください。推奨事項：

• 専用の、消去可能なマシン（または VM／コンテナー）を使用してください — メインのコンピューターは使用しないでください。ローカルモードでは、エージェントと操作対象が同じ PC 上で動作します。便利ですが、影響範囲が最も大きくなるため、可能であれば別のマシンを使用してください。
• 最小限の権限を持つ OS アカウントで実行してください。管理者／root として実行してはいけません — エージェントは、そのアカウントで可能な操作をすべて実行できます。
• シークレットやログイン済みアカウントを操作対象から遠ざけてください — 保存済みパスワード、認証済みセッション、プロンプト内の認証情報は使用しないでください。
• 重大または取り消し不能な操作（ソフトウェアのインストール／削除、メッセージの送信、金融取引、利用規約への同意など）では、人間が常に関与するようにしてください。範囲の定まっていないタスクを、エージェントに任せきりにしないでください。
• ネットワークを分離してください（ドメインの許可リストなど）。悪意のあるコンテンツやインジェクションを含むコンテンツへの接触を制限できます。
• 画面やウェブから読み取った内容はすべて信頼できない入力として扱い、機密データや操作から遠ざけてください。
• すぐに使える緊急停止手段を確保してください。 hid.release_all を使うと、エージェント側で押したままになっているキーとボタンがすべて解放されます。HID デバイスの USB ケーブルを物理的に抜く方法が最も確実な停止手段であり、エージェントの入力経路を完全に遮断できます。

アクセシビリティや管理された RPA など、他者のためにこれを導入する場合は、リスクをエンドユーザーに知らせ、同意を得てください。

ツール

17 個のツールが登録されます。常時利用可能な hid.* 入力ツールが 14 個、hid.screenshot（オプトイン — --allow-screenshot を指定しない限り無効）、読み取り専用の device.* 診断ツールが 2 個です。これは、起動ログの 14 HID tools + 2 device tools registered という行と一致します（--allow-screenshot フラグを指定すると、これに hid.screenshot が追加され、合計 17 個になります）。

ツール	バージョン	用途
hid.click	v1.0	(x, y) の位置をクリックします
hid.move	v1.0	マウスを (x, y) の位置に移動します
hid.hover	v1.0	(x, y) の位置に移動してから、動かさずに待機します
hid.type	v1.0	ASCII テキストを入力します（US 配列）
hid.scroll	v1.0	ホイールで上／下にスクロールします
hid.key	v1.0	名前で指定したキーまたはショートカットを押します（enter、ctrl+c、…）
hid.release_all	v1.0	緊急停止 — 押したままのボタンとキーをすべて解放します
hid.mouse_button_down	v1.1	マウスボタンを解放せずに押します（ドラッグの開始）
hid.mouse_button_up	v1.1	押したままのマウスボタンを解放します（ドラッグの終了）
hid.drag	v1.1	ボタンを押したまま、ある地点から別の地点までドラッグします
hid.key_press	v1.1	キー／ショートカットを解放せずに押します
hid.key_release	v1.1	押したままのキーを解放します（引数なしの場合はすべて解放します）
hid.hold_key	v1.1	キーを押し、待機してから解放します
hid.batch	v0.4.0	事前に計画した 10 個以下の HID アクションを、1 回の呼び出しで（厳密な順序で）実行します
hid.screenshot	v1.0	モニターまたは region のスクリーンショットを撮影します — デフォルトは JPEG q80、可逆形式にするには format='png' を指定します。max_width で返される画像の幅に上限を設定します。markers を指定すると、ビジョンモデルで座標を扱うためのキャリブレーションマーカーが 2 つ追加されます（オプトイン、--allow-screenshot が必要です）
screen.windows	v0.5.0	タイトルと画面上の矩形を含む、表示中の最上位ウィンドウを一覧表示します。これにより、キャプチャを 1 つのウィンドウに切り抜けます。Windows では、各項目に visible_fraction も含まれます。これは、実際にウィンドウが前面に表示されている割合です。ほかのウィンドウに覆われたウィンドウの矩形をキャプチャすると、実際にはそのウィンドウを覆っているものがキャプチャされるためです。さらに enabled と raise_point も含まれます。これら 3 つの値は、測定できなかった場合（macOS、またはサンプリングするには矩形が小さすぎる場合）は含まれません。foreground は両方のプラットフォームで測定されますが、OS に問い合わせられなかったまれな場合は同様に含まれません。また、minimized は Windows でのみ測定されます。値が含まれない場合は未測定を意味し、測定したうえで問題がなかったという意味ではありません（オプトイン、--allow-screenshot が必要です。Windows + macOS）
device.list	v1.0	HID ボードの候補となるポートを一覧表示します
device.info	v1.0	アクティブな接続情報を表示します
座標と動作。 クリック／移動／ホバーの座標は、デフォルトでは絶対座標です。
サーバーは OS のカーソル位置（Win32 ／ CoreGraphics ／ X11）を取得し、指定位置までのオフセットを計算して、ファームウェアに相対差分を送信します。そのため、{"x": 640, "y": 360} は画面上のそのピクセル位置に到達します。relative=true を渡すと、OS への問い合わせを省略し、生のピクセル差分を送信します。OS のカーソル位置を取得できない場合（Wayland、または OS への問い合わせに失敗した場合）、呼び出しは明示的なエラーを返します。推測で間違った場所をクリックすることはありません。hid.drag は mouse_button_down → 滑らかな move → mouse_button_up を組み合わせます。v1.1 のボタン／キー押下ペア（mouse_button_*、key_press ／ key_release、hold_key）は、Computer-Use Anthropic（CUA）のアクションセットに対応しています。hid.batch は、これらのアクションを事前に計画した短いリスト（≤10）で厳密な順序どおりに実行します。これは、すでに把握しているアクションリスト（例：ソルバーが計算した複数の固定座標）をまとめて送信するためのトランスポート上の利便機能であり、制御フローや「操作 → 観察 → 判断」のレイヤーではありません。そのためには、引き続き個別に呼び出してください。連続クリックは、OS にまとめられたり無視されたりしないよう、デフォルトで短い間隔（約50 ms）が自動的に設定されます。各操作で delay_ms を指定して上書きできます（無効にするには 0 を設定します）。

ツールの選択。 このサーバーには、エージェントが物理 HID を適切な場合にのみ選ぶよう促す組み込みの選択ガイダンスが備わっています。initialize の応答に含まれる MCP の instructions フィールドに加え、すべての hid.* の説明の先頭に付加されるツールごとの HID_PREFIX があります（そのため、クライアントがサーバーレベルのフィールドを無視してもガイダンスが伝わります）。どちらも同じ内容で、ファイル／ブラウザー／OS API では実行できない場合、またはユーザーが物理キーボード／マウス入力を明示的に求めた場合に限り、フォールバックとして hid.* を優先するよう案内します。読み取り専用の device.* ツールにはプレフィックスがありません。

例

ほとんどのエージェントは、MCP クライアント（Claude Desktop ／ Code、Cursor など）を通じて clawtouch-mcp にアクセスします。動作確認済みのクライアント用に、そのままコピー＆ペーストできる設定が examples/integrations/INTEGRATIONS.md にあります。

代わりに独自の Computer Use ループを構築する場合は、examples/computer_use/ に、エージェントのアクションを ClawTouch HID 経由で実行する2つのリファレンス実装があります。

• Claude Computer Use → HID — computer_20251124 ツールを使用する client.beta.messages.stream
• OpenAI CUA → HID — computer-use-preview を使用する Responses API

アプリケーションごとの LLM 向けガイダンスとして、clawtouch-skills は、LLM が特定のアプリを操作する前に読み込める Markdown の操作マニュアルをまとめた関連リポジトリです。スキルはあくまで補助的なガイダンスであり、何をするかは引き続き LLM が判断します。

動作を見る

ブリッジに接続してサーバーを起動すると、任意の MCP クライアント（Claude Desktop、Cline、または独自のループ）が、stdio 経由でプレーンな MCP の tools/call を送信します。各呼び出しは、実際のハードウェアに実際の USB-CDC フレームとして送信されます。 合成されたものは一切ありません。

$ clawtouch-mcp --port COM7
[INFO] connected to Pico 2 on COM7 (serial: E660ABCD12345678)
[INFO] screen auto-detected: 2560x1440 (Windows SM_CXSCREEN/SM_CYSCREEN)
[INFO] 14 HID tools + 2 device tools registered; listening on stdio

# client → server : one click, then one typed string
#                   (the cursor and keys actually move)
→ tools/call  hid.click  {"x": 640, "y": 360}
← result       "clicked at (640, 360)"

→ tools/call  hid.type   {"text": "Hello from MCP"}
← result       "typed 14 chars in 0.42s"

許容される利用

このサーバーは、アクセシビリティ、RPA、テスト自動化、入力ドライバーをインストールできないキオスクなど、正当な用途を目的として構築されています。このプロジェクトは、次のようなユースケースをサポート、文書化、支援しません。

• 対象プラットフォームの不正防止、不正利用防止、レート制限、リスク管理の仕組みを回避、迂回、妨害すること。
• ユーザーが適法に所有していないアカウント、または操作する明示的な権限を持たないアカウントを操作すること。
• ユーザーの管轄区域において、対象アプリケーションの利用規約で禁止されていること。
• 適用法令に違反すること。これには、以下が含まれますが、これらに限定されません。中国の不正競争防止法第13条（インターネット分野に関する規定。公布日：2025-06-27、施行日：2025-10-15）。技術的な管理措置の回避など、不適切な手段による他の事業者のデータの取得または利用を対象とします。個人情報保護法、サイバーセキュリティ法、および他の管轄区域における同等の法律。

これらの記述は、メンテナーによるサポートおよびドキュメントの範囲を示すものです。すべてのソースコードの利用、変更、再配布を引き続き規定するMIT Licenseに、これらの記述による追加制限が課されるものではありません。ユーザーは、自身の具体的なユースケースが適用法令および対象プラットフォームのToSに適合するかどうかを、各自の責任で評価する必要があります。

コンテンツ生成 — 対象外

clawtouch-mcp は、ハードウェアのHID操作（マウス／キーボード／スクロール／キーの組み合わせ／スクリーンショット）をMCPツールとして公開します。テキスト、画像、音声、動画のコンテンツを生成、合成、推奨、またはその他の方法で作成することはありません。呼び出し元のLLMエージェントがコンテンツの生成主体であり、生成されたコンテンツ、およびその管轄区域で適用されるコンテンツのラベル付けまたはモデレーション義務（例：中国のAI生成コンテンツラベル付与措置、2025-09-01施行）の遵守について、単独で責任を負います。

ハードウェア

このサーバーは、次のハードウェアと通信できます。

1. ClawTouch HID device — ファームウェア書き込み済みの開発キットで、プラグアンドプレイで利用できます（中国国内から発送）。
   clawtouch.cn を参照してください。
2. clawtouch-hid を実行する任意のRP2350ボード — OSSファームウェアとプロトコルモジュール（wire epoch 1、固定されたエンベロープ）は、独立した公開リポジトリで管理されています。
   Pico 2（約$8）を購入してファームウェアを書き込めば完了です。

どちらも同じワイヤープロトコルを使用するため、サーバーはどちらと通信しているかを気にしません。

FAQ

ClawTouch のアカウント／API キー／クラウドサービスは必要ですか？ いいえ。このサーバーは HID ボードと USB シリアル通信を行うだけです。ネットワークへの接続はありません。データがマシンの外に送信されることもありません。

ClawTouch のハードウェアを購入せずに利用できますか？ はい。8 ドルの Raspberry Pi Pico 2 を購入し、オープンソースの clawtouch-hid ファームウェアを書き込めば、 このサーバーは完成品デバイスと同じ方法で通信します。

JavaScript／TypeScript 版はありますか？ まだありません。clawtouch-bridge-sdk（Python + Node）の開発を予定しています。詳しくは オープンソースのロードマップをご覧ください。

hid.screenshot が ImportError: dlopen(... _imaging ...) code signature ... different Team IDs で失敗しますか？ ホストの Python で強化ランタイムの ライブラリ検証 が有効になっており、ホスト自身の Team ID で署名されたネイティブ拡張機能しか許可されていないため、Pillow の _imaging がブロックされています（一部のバンドル版／ランチャー版 Python で発生します）。サーバーはこれを自動検出し、ネイティブ拡張機能を使わない mss-png バックエンドに切り替えて、メタデータに説明用の note を含む PNG を返します。特別な操作は不要です。mss 自体は純粋な Python（ctypes → CoreGraphics。プラットフォームフレームワークのため対象外）なので正常に読み込まれます。ブロックされるのは Pillow のコンパイル済み拡張機能だけです。強制的に切り替えるには、--screenshot-backend mss-png を指定するか、軽量版の pip install 'clawtouch-mcp[screenshot-min]'（mss のみ）をインストールしてください。Pillow（JPEG + 高品質なリサイズ）を使うには、ライブラリ検証が有効になっていない Python から clawtouch-mcp を実行するか、ホストの Python に com.apple.security.cs.disable-library-validation エンタイトルメントを付与してください。いずれの場合も、スクリーンショットの backend フィールドと scale_x／scale_y から、エージェントはどの方式で取得されたかを判断できます。クリック座標は必ず scale_x／scale_y で割ってください。

関連プロジェクト

MCP／コンピューター操作のエコシステムには、LLM エージェントにデスクトップの操作権限を与えるプロジェクトがすでにあり、大きく 2 つのグループに分かれています。対象 PC 上で動作するソフトウェアのみの MCP サーバーには、domdomegg/computer-use-mcp、AB498/computer-control-mcp、さまざまな mcp-pyautogui 実装、そして ByteDance の UI-TARS があります。これらはプロセス内で PyAutoGUI／OS の入力 API を呼び出します。導入の手間が最小で、ハードウェアは不要です。ハードウェアブリッジ型サーバーは、別の USB デバイスから入力を送信します。sunasaji/mcp-serial-hid-kvm（CH9329／CH9350L USB-HID ASIC とキャプチャカードを使用）はアーキテクチャ上、最も近い直接的な同種プロジェクトです。また、CMU の HIDAgent（Bigham、2026-01。30 ドル未満の RP2040 + HDMI-to-USB + CH340 シリアルブリッジを使用し、Python ライブラリとして提供）は、学術分野で最も近い同種プロジェクトです。clawtouch-mcp は 2 つ目のグループに属し、オープンファームウェアの clawtouch-hid スタックと組み合わせているため、ワイヤープロトコルはユーザーが拡張でき、ファームウェアも監査可能です。固定機能の ASIC ではありません。

ClawTouch の代えがたい強みは、本物のハードウェア HID 経路です。OS には実際の物理キーボード／マウスとして認識されます。この本物の HID と入力側にドライバーが不要な点が、アクセシビリティや互換性のテストで役立ちます。USB デバイスから入力を送る必要がない場合は、上記のソフトウェアのみのサーバーのほうがシンプルです。

オープンソースのロードマップ、コントリビューション、ライセンス

ファームウェア、ワイヤープロトコル、MCP サーバー、スキルテンプレートはすべて MIT ライセンスです。

コンポーネント	ステータス
clawtouch-mcp（このリポジトリ）	✅ リリース済み
clawtouch-hid — ファームウェア + プロトコルモジュール、ワイヤーエポック 1	✅ リリース済み
clawtouch-skills — LLM エージェント向け Markdown スキルファイル	✅ リリース済み
clawtouch-bridge-sdk — Python + Node HID SDK	🔵 今後の予定

貢献

以下の PR を歓迎します：既存の HID プリミティブに対応する新しい MCP ツール、バグ修正、クライアント統合の例、ドキュメントの改善、英語以外の README 翻訳。

以下の PR は受け付けていません：エージェントループのロジックやアプリケーションレベルの機能（意図的に対象外です。利用上の許容事項を参照）、特定のアプリケーション向けのアダプター（アプリ固有のノウハウは、Markdown 形式で clawtouch-skills に記載してください）。

clawtouch-mcp は Tinqiao Technology（ClawTouch を開発するチーム）がメンテナンスしています（clawtouch.cn）。

ライセンス

MIT © Beijing Tinqiao Technology Co., Ltd. — LICENSE（英語、正式版）および LICENSE.zh-CN.md（非公式の中国語訳、参考用）を参照してください。

サードパーティの依存関係とそのライセンスは NOTICE に記載されています。このリポジトリ内で言及されている商標（ClawTouch、Tinqiao、サードパーティの商標）は、TRADEMARKS.md で別途取り扱っています。MIT ライセンスは、いかなる商標権も付与しません。

お問い合わせ：[email protected]。

アーキテクチャ概要

flowchart LR
    A["<b>LLM Agent</b><br/><sub>Claude Desktop / Cline /<br/>Cursor / OpenClaw / Hermes / ...</sub>"]
        -->|"stdio<br/>JSON-RPC<br/>MCP 2024-11-05"| B["<b>clawtouch-mcp</b><br/><sub><i>this repo</i><br/>MCP server + 14 HID + 2 device tools</sub>"]
    B -->|"USB-CDC<br/>v1.0 framed bytes"| C["<b>Pico 2</b><br/><sub>+ ClawTouch HID firmware<br/>(RP2350 / CircuitPython)</sub>"]
    C -->|"USB HID<br/>reports"| D["<b>Target OS</b><br/><sub>Windows / macOS / Linux<br/>standard HID driver stack</sub>"]
    classDef this fill:#fef3c7,stroke:#d97706,stroke-width:3px,color:#78350f;
    class B this;

このリポジトリは MCP サーバーの中継部分です。MCP ツールの呼び出しを USB-CDC 経由のフレーム化されたバイト列に変換し、ファームウェアがそれを標準の USB HID レポートに変換します。