Realhands — Real Desktop Computer Use

computer-use-mcp ("realhands")

人間と同じように、実際のマウスを動かし、クリックや入力を行い、実際の画面を読み取ることで、Claude があなたの実際のコンピューターを操作できるMCP サーバーです。

OpenAI Operator、browser-use、Playwright エージェントのように、独立したログアウト状態の Chrome を起動するものとは異なり、物理的な OS カーソルとキーボードを操作します。そのため、あなた自身のログイン済みセッションを使って、自分の Chrome で動作します。ほかのすべてのアプリでも同様です。どのウェブサイトから見ても、キーボードの前にいるのは人間だからです。

ステータス：稼働中で、実環境で十分に検証済みです。 Claude Code のユーザースコープ MCP として realhands（ツール mcp__realhands__computer）に登録され、2026-06-02 から ✓接続済みです。 2026-06-09 には、ユーザーの実際のログイン済み Chrome を操作し、Google Play Console へのデプロイを一通り完了しました（アプリのアップロード、リリースノート、申請まで）。

サーバーが computer-use ではなく realhands として登録されているのは、 「computer-use」という名前が Claude Code で予約されているためです。

仕組み

Claude（Desktop または Code）がエージェントのループを担います。タスクを入力すると、Claude は単一の computer ツールを呼び出し、「見る → 考える → 行動する」のサイクルを実行します。

見る — screenshot が実際の画面を返します（位置を正確に把握するため、約1280pxに縮小されます） → 考える — Claude が次のアクションとピクセル座標を選びます → 行動する — サーバーが実際のマウスを動かし、実際のキーボードで入力します → 各アクションの後に最新のスクリーンショットが自動的に返され、これが繰り返されます。

クリックを正確な位置に行うため、Windows 固有の詳細が2つあります（src/screen.py）。

• DPI 認識 — インポート時に SetProcessDpiAwareness(2) を設定するため、ディスプレイの拡大縮小率が125％／150％などの場合でも、スクリーンショットのピクセルと pyautogui のカーソル座標が一致します。
• ステートレスな座標の拡大縮小 — 送信前に、スクリーンショットを最長辺が COMPUTER_USE_MAX_DIM 以下になるよう縮小します（LANCZOS）。受け取ったクリック座標は実際のピクセル座標に拡大し直されます。倍率はモニターのジオメトリと MAX_DIM のみで決まるため、どのスクリーンショットが最後に実行されたかに左右されず、座標の対応付けが行われます。 座標は対象モニター内に収まるように制限されるため、誤ってクリックしても画面外には飛びません。 各軸は28pxのビジョンパッチ単位で切り捨てられるため、2つの軸の倍率にはごくわずかな差が生じることがあります（2.2％未満）。to_real() は各軸を個別の倍率で対応付け、正確さを保ちます。

マルチモニター： すべての呼び出しでは、任意の monitor インデックスを指定できます（1 = プライマリ、2.. = その他、0 = 仮想デスクトップ全体）。action="monitors" で構成を列挙します。 画面がプライマリの左側または上側にある場合、原点が負になることがありますが、to_real() がオフセットを処理します。クリックするスクリーンショットと同じモニターを指定してください。

アーキテクチャ

src/realhands/
  server.py   FastMCP server "computer-use"; the single `computer` tool (action enum
              modeled on Anthropic's reference computer_20250124 tool); runs one
              action or a batch of `steps`, then returns status text + at most one
              screenshot
  screen.py   DPI awareness, mss capture, patch-aligned downscale, model-space ->
              real-pixel mapping, unchanged-screen detection
  input.py    pyautogui mouse/keyboard execution; xdotool-style key-name translation
              (Return, Page_Down, ctrl+a, super, ...); clipboard-paste fast path for
              long/Unicode/multiline typing (preserves your existing clipboard);
              activate_window via win32 AttachThreadInput
  safety.py   kill switches + lazy arm / stand-down lifecycle
  config.py   .env-driven configuration (all defaults are sensible; .env is optional)
install.py    one-shot installer: venv, deps, .env, Claude Desktop registration

スタック：Python 3.10/3.11 · mcp（FastMCP、stdio）· pyautogui · mss · pillow · pynput · keyboard · pyperclip · python-dotenv — さらに activate_window 用の pygetwindow と pywin32

computer ツール

action パラメーターを持つ単一のツールです。

アクション	動作
screenshot	画面をキャプチャします（タスクは必ずこれから開始してください）
cursor_position	実際のマウス位置を報告します
monitors	検出されたモニターを一覧表示します（マルチスクリーン環境向け）
mouse_move	カーソルを coordinate まで滑らかに移動します
left_click / right_click / middle_click / double_click / triple_click	coordinate（または現在位置）をクリックします
left_click_drag	text="x1,y1" の位置から coordinate=[x2,y2] までドラッグします
left_mouse_down / left_mouse_up	左ボタンを押す／離します
scroll	coordinate の位置でスクロールします（scroll_direction と scroll_amount でノッチ数を指定）
type	text を入力します（長文／Unicode／複数行の場合はクリップボード貼り付けを使用）
key	キーまたはキーの組み合わせを押します — "Return"、"ctrl+s"、"alt+Tab"
hold_key	指定したキーを duration 秒間押し続けます
activate_window	タイトルの一部を指定してアプリを前面に表示します（Windows のフォアグラウンドロックを回避でき、タスクバーをクリックするよりはるかに確実です）
wait	duration 秒待機してからスクリーンショットを撮影します
stop	停止します：STOP オーバーレイを閉じ、パニック用ホットキーを解除します（最後のアクションとして呼び出してください）

座標は最新のスクリーンショットのピクセル空間で指定します。サイズは キャプチャごとに報告されます。スクリーンショット以外のアクションの後は、 UI が落ち着くまでツールが約 0.4 秒待機し、新しいスクリーンショットを返します。

トークンの節約

デスクトップ操作では、スクリーンショットが大きなコストになります。一度だけではありません。 すべての画像は会話に残り、以降の各ターンで履歴として再送されます。Claude の ビジョン機能は 28×28 のパッチ単位で課金されます — tokens = ⌈w/28⌉ × ⌈h/28⌉ — そのため、このサーバーはコストを抑えるために次の 4 つの対策を行います。

ステップの一括実行。 アクションごとに呼び出す代わりに、steps（アクション辞書のリスト）を渡すと、 実行全体の最後にスクリーンショットを 1 枚だけ取得します。

{"steps": [{"action": "left_click", "coordinate": [420, 300]},
           {"action": "type",  "text": "[email protected]"},
           {"action": "key",   "text": "Tab"},
           {"action": "type",  "text": "secret"},
           {"action": "key",   "text": "Return"}]}

これにより、視覚トークンは 5 625 から 1 125 に、ラウンドトリップは 5 回から 1 回に減ります。 後者の節約効果のほうが大きいのは、ターンを 1 回減らすごとに会話履歴全体の再送も不要になるためです。 ステップが失敗すると実行は停止し、失敗したステップが報告されますが、画面は返されます。 最後の画像も省略するには、"screenshot": false を追加してください。

パッチに合わせた縮小。 寸法が 28 の倍数でない場合、ほとんどピクセルを含まない 部分的なパッチ行／列にもコストがかかります。1920×1080 のプライマリ画面では、 デフォルトの 1260×700 はちょうど 45×25 パッチ = 1 125 トークンです。一方、1280×720 では 1 196 トークンとなり、ピクセル数が 1.5% 少ないだけで、コストは 6% 高くなります。

変化のない画面の抑制。 前回送信した画像から変化したピクセルが CHANGE_THRESHOLD 未満の場合、 スクリーンショットの代わりにテキスト 1 行を返します。実際のデスクトップでは、時計、キャレット、 ホバー状態などが変化するため、バイト単位で完全に同一のフレームが 2 枚生成されることはありません。 そのため、これは一致判定ではなく、しきい値による判定です。抑制が連続して MAX_SKIPS 回行われると、 画像を 1 枚強制送信します。これにより、以前の画像がコンテキストの圧縮で失われた場合でも、 モデルが状況を把握できなくなるのを防ぎます。

適切なサイズの画像。 COMPUTER_USE_MAX_DIM は、画面把握の精度とコストのバランスを調整します — 1920×1080 のプライマリ画面では、1792 → 2 304 トークン、1260 → 1 125（デフォルト）、 1036 → 777、896 → 576 です。長辺は 2576 px 以下にしてください。tool_result 内で返される画像が モデルの上限を超えると、縮小されずに 拒否 されます。

COMPUTER_USE_IMAGE_FORMAT ではトークン数は節約できません — Claude はピクセル寸法に基づいて課金するため、 同じスクリーンショットなら JPEG も PNG もコストはまったく同じです。JPEG で減らせるのはペイロードの バイト数だけです（この場合は約 977 KB → 約 141 KB）。その代わり、小さな文字の読みやすさが損なわれる リスクがあります。応答時間の短縮には役立ちます。

Safety — 実際のマシンを操作します

これは完全に自律的に動作し、各アクションの前に確認を求めません。独立したキルスイッチが3つあります（src/safety.py）。

1. フェイルセーフコーナー — マウスを左上隅に勢いよく動かすと、pyautogui が FailSafeException を発生させ、アクションを即座に中止します。
2. パニックホットキー — Ctrl+Alt+Q（設定可能）を押すと、サーバープロセスを強制終了します（os._exit(1)）。
3. STOP オーバーレイ — 現在のアクションを表示する、常に最前面のウィンドウ（右上）です。大きな赤い ■ STOP AGENT ボタンを押すと、こちらもプロセスを強制終了します。

遅延アーム／スタンドダウン： オーバーレイとグローバルパニックホットキーは、サーバー起動時ではなく、タスクの最初のアクションで遅延して有効になります。アイドル状態のセッションでは何も表示されず、ホットキーも登録されません。タスクの終了時にエージェントが action="stop" を呼び出すとスタンドダウンし、次のアクションで自動的に再び有効になります。（STOP オーバーレイは永続するウィンドウを1つだけ使用し、休止中は破棄せずに非表示にします。ウィンドウの再作成はクラッシュの原因になる可能性がありました。）オプションのアイドル時自動スタンドダウンは、COMPUTER_USE_IDLE_STOP で利用できますが、デフォルトでは無効です。ツール呼び出しの合間にエージェントが思考する時間は、短いアイドル時間を簡単に超えるため、ゼロ以外の値を設定すると、タスクの途中でエージェントがスタンドダウンする可能性があります。

操作のペース調整も、制御を保つのに役立ちます。各アクションの後に設定可能な一時停止（COMPUTER_USE_PAUSE）を挟み、カーソルは瞬間移動ではなく滑らかに移動します（COMPUTER_USE_MOVE_DURATION）。そのため、動作を見守り、途中で中断できます。

金銭の支出、メッセージの送信、データの削除が可能な操作を、監視せずに実行させないでください。

インストール

Python 3.10 または 3.11 が必要です（3.13 以降は未テストです。3.14 ベータ版は使用しないでください）。

推奨：uvx（常に最新バージョン）

事前のインストールは不要で、すべてのリリースが自動的に適用されます。uvx はサーバーの起動ごとに公開済みの最新バージョンを解決するため、アップグレードするには MCP クライアントを再起動するだけです。uv が必要です。

uvx realhands@latest

uv がすでにキャッシュしているバージョンを再利用する場合は、@latest（uvx realhands）を省略してください。

PyPI からインストール（バージョン固定）

pip install realhands

これにより、realhands コンソールスクリプトと、インポート可能な realhands パッケージがインストールされます。サーバーは realhands または python -m realhands.server で起動できます。

バージョンを固定して変更されないようにしたい場合や、起動時にマシンがオフラインの可能性がある場合は、uvx の代わりにこちらを選んでください。uvx realhands@latest は起動のたびに PyPI への接続が必要です。その代わり、アップグレードは手動で行う必要があります。

pip install --upgrade realhands

次に MCP クライアントを再起動してください。クライアントはセッション開始時にサーバーを接続するため、実行中のセッションでは再起動するまで古いコードが使われます。

ソースからインストール（Claude Desktop への登録を含む）

git clone https://github.com/kanishka089/computer-use-mcp
cd computer-use-mcp
py -3.10 install.py

これにより .venv/ が作成され、パッケージと依存関係が編集可能モードでインストールされます。また、.env が存在しない場合は .env.example が .env にコピーされ、Claude Desktop の設定にサーバーが登録されます（既存の設定はバックアップされます）。Claude Desktop を再起動し、computer-use ツールを探してください。

Claude Code

realhands という名前のユーザースコープの stdio サーバーとして登録してください。この形式では自動アップグレードされます。新しいセッションごとに最新のリリースが解決されるため、更新を気にする必要はありません。

claude mcp add realhands --scope user -- uvx realhands@latest

その後、すべてのプロジェクトでツールが mcp__realhands__computer として表示されます。

代わりに pip でインストールし、バージョンを固定したい場合は、パッケージがインストールされている Python を指定してください（アップグレードする際は、自分で pip install --upgrade realhands を実行してください）。

claude mcp add realhands --scope user -- python -m realhands.server

以前のバージョンですでに登録済みですか？ 自動アップグレード形式に切り替えてください。

claude mcp remove realhands --scope user
claude mcp add realhands --scope user -- uvx realhands@latest

セッション中に MCP の登録を削除して再追加すると、そのセッションからの接続は切断されます。新しい登録は、次回 Claude Code を起動したときに反映されます。

アップグレード

0.1.xをお使いですか？ アップグレードしてください。mcp 2.0ではAPI 0.1.xのインポートが削除されたため、mcp 1.xが解決されていた時期にインストールした環境は引き続き動作しますが、再インストールしたりマシンを移行したりすると、起動できないサーバーになります。0.2.1以降は両方に対応しています。v0.2.1を参照してください。

おすすめ：自動アップグレード形式に切り替える（一度だけ）

これで以後はアップグレード作業が不要になります。クライアントを再起動するたびに、最新リリースが適用されます。

claude mcp remove realhands --scope user
claude mcp add realhands --scope user -- uvx realhands@latest

Claude Codeを再起動します。（セッション中にMCPを削除して再追加すると、そのセッションからの接続が切れます。新しい登録は次回の起動時に有効になります。）

pipを使い続ける場合

サーバーが実際に実行するインタープリターをアップグレードしてください。たまたまpipが解決したものではありません。仮想環境にインストールした場合や、複数のPythonがある場合、pip install --upgrade realhandsをそのまま実行すると、別の環境がアップグレードされ、サーバーは古いバージョンのままになることがあります。アップグレードが「反映されない」最も一般的な原因です。

まず、インタープリターを確認します。

claude mcp get realhands

Command:の行を確認してください。それがPythonです。次に、そのインタープリターを明示してアップグレードします。

& "C:\path\from\that\Command line\python.exe" -m pip install --upgrade realhands

Command:が単なるpythonの場合は、pip install --upgrade realhandsで問題ありません。

アップグレードが反映されたことを確認してから、Claude Codeを再起動します。

& "C:\path\to\python.exe" -c "import realhands; print(realhands.__version__)"

ソースからインストールした場合

install.pyはパッケージを編集可能モードでインストールするため、git pullだけで十分です。チェックアウトした内容がそのままインストール済みのバージョンになります。クライアントを再起動してください。

使い方

そのまま依頼してください。たとえば、次のように伝えます。

スクリーンショットを撮り、Chromeを開いてYouTubeにアクセスし、「lofi」を検索してください。

実際のカーソルの動きと、ログイン済みのChromeの応答を確認できます。実環境での実績として、ユーザー自身のログイン済みChromeセッションで、Google Play Consoleのリリースフロー全体を自律的に完了しています。

設定（.env、任意 — デフォルト値のままで問題ありません）

変数	デフォルト	意味
COMPUTER_USE_MAX_DIM	1260	Claudeに送信するスクリーンショットの最長辺。精度とコストを調整する主な設定です（トークンの節約を参照）
COMPUTER_USE_PATCH_ALIGN	1	各辺を28px単位で切り下げ、端数のパッチにトークンを使わないようにします（各ショットで約6%節約）
COMPUTER_USE_CHANGE_THRESHOLD	0.002	ピクセルの移動量がこの割合未満の場合、スクリーンショットを省略します（0 = 常に送信）
COMPUTER_USE_MAX_SKIPS	6	この回数だけ連続して省略した後、実際のスクリーンショットを強制します
COMPUTER_USE_MONITOR	1	デフォルトのモニター（1 = プライマリ、2以降 = その他、0 = すべての画面）。呼び出しごとに上書きできます
COMPUTER_USE_IMAGE_FORMAT	png	png（鮮明なテキスト）またはjpeg（ペイロードが小さい）。トークン節約にはなりません。コストはバイト数ではなくピクセル寸法で決まります
COMPUTER_USE_PAUSE	0.15	各pyautogui操作後の遅延（中断可能性）
COMPUTER_USE_PANIC_HOTKEY	ctrl+alt+q	グローバルな緊急停止ホットキー
COMPUTER_USE_OVERLAY	1	STOPオーバーレイウィンドウを表示します
COMPUTER_USE_MOVE_DURATION	0.4	カーソルの移動時間（人間らしい動き）
COMPUTER_USE_IDLE_STOP	0	指定したアイドル秒数が経過すると自動的に停止します（0 = 停止しない。action="stop"の場合のみ停止）

既知の注意点

• エージェントがターン間でアイドル状態になると、MCP 接続が切断されます。 Claude がターン間で思考中または待機中に、realhands への stdio 接続が気づかないうちに切断されることがあります。対処法：screenshot アクションを実行すると、気づかないうちに再接続されます。重要な点として、Connection closed で「失敗した」アクションも、実機では実行済みの場合がよくあります。再試行する前にスクリーンショットを撮って実際の画面状態を確認してください。そうしないと、二重クリックや二重送信が発生する可能性があります。
• クリック座標はスクリーンショットのモニターと一致させる必要があります。 monitor=2 でスクリーンショットを撮影し、その後 monitor=2 を指定せずにクリックすると、クリックはプライマリモニターに届きます。
• タスクバーよりも activate_window を使ってください。 Windows のフォアグラウンドロックにより、タスクバーのクリックは信頼性が低く、アイコンが点滅するだけのことがあります。activate_window は AttachThreadInput と Z オーダーの切り替えに加え、最小化／復元へのフォールバックも使用するため、アプリの切り替えにはこちらを優先してください。
• Python 3.13／3.14 では実行しないでください。 テスト済みなのは 3.10／3.11 のみです。インストーラーにも警告が表示されます。
• 長文や Unicode 文字列の入力にはクリップボードが使われます。 クリップボードの内容は保存・復元されますが、クリップボードを監視するものには、貼り付けたテキストが一時的に表示されます。

セルフテスト

python -m realhands.screen

画面をキャプチャし、実際の寸法と送信された寸法およびスケール係数を出力します。また、test_capture.png に書き込み、座標の往復チェック（中央と両方の隅）を実行します。