Claude KVM

Claude KVM

リモートアクセス、人工知能

claude-kvm.ai

Claude KVM は、VNC 経由でリモートデスクトップ環境を操作する MCP ツールです。薄い JS プロキシレイヤー（MCP サーバー）と、macOS システム上で動作するプラットフォームネイティブな Swift VNC デーモンで構成されています。

ヒント

Phantom-WG は優れた代替手段になるかもしれません。 VNC サーバーを独自のネットワーク内に分離しながら、セルフホスト VPN のパフォーマンスと、あわせて得られるプライバシー機能を活用できます。

ライブテストの実行結果

• 統合テスト
• Mac 統合テスト
• Mac 電卓テスト
• Mac 関数電卓テスト
• Mac Safari ブラウジングテスト
• Mac ドラッグ＆ドロップテスト
• Mac チェステスト
• Mac チェス直接テスト
• Mac Phantom-WG インストールテスト

メモ

テストは GitHub Actions 上で透明性を保って実施され、CI 環境で各ステップを確認できます。テストの最後には、統合テストの成否にかかわらず、セッション中にエージェントが実行した各ステップのスクリーンショットと、セッション全体を記録した .mp4 動画が用意されています。録画とスクリーンショットを確認すると、エージェントが各段階をどのように進めたか、タスクにどれくらい時間がかかったか、システムプロンプトに基づいてどのような判断をしたかを確認できます。これらの例は、ご自身の環境で MCP サーバーに使用するシステムプロンプトや指示を作成する際の参考として利用できます。

警告

これらの実行に添付されたアーティファクトは、GitHub のアーティファクト保持ポリシーにより、有効期限が切れている場合があります。永続的なコピーは Persist Artifacts ワークフローで用意されており、press-kit ブランチの artifacts/ ディレクトリから、実行 ID を使っていつでもアクセスできます。

アーキテクチャ

graph TB
    subgraph MCP["MCP Client (Claude)"]
        AI["Claude"]
    end

    subgraph Proxy["claude-kvm · MCP Proxy (stdio)"]
        direction TB
        Server["MCP Server<br/><code>index.js</code>"]
        Tools["Tool Definitions<br/><code>tools/index.js</code>"]
        Server --> Tools
    end

    subgraph Daemon["claude-kvm-daemon · Native VNC Client (stdin/stdout)"]
        direction TB
        CMD["Command Handler<br/><i>PC Dispatch</i>"]
        Scale["Display Scaling<br/><i>Scaled ↔ Native</i>"]

        subgraph Screen["Screen"]
            Capture["Frame Capture<br/><i>PNG · Crop · Diff</i>"]
            OCR["OCR Detection<br/><i>Apple Vision</i>"]
        end

        subgraph InputGroup["Input"]
            Mouse["Mouse<br/><i>Click · Drag · Move · Scroll</i>"]
            KB["Keyboard<br/><i>Tap · Combo · Type · Paste</i>"]
        end

        VNC["VNC Bridge<br/><i>LibVNCClient 0.9.15</i>"]

        CMD --> Scale
        Scale --> Capture
        Scale --> Mouse
        Scale --> KB
        Capture -.->|"framebuffer"| VNC
        Mouse -->|"pointer events"| VNC
        KB -->|"key events"| VNC
    end

    subgraph Target["Target Machine"]
        VNC_Server["VNC Server<br/><i>:5900</i>"]
        Desktop["Desktop Environment"]
        VNC_Server --> Desktop
    end

    AI <-->|"stdio<br/>JSON-RPC"| Server
    Server <-->|"stdin/stdout<br/>PC (NDJSON)"| CMD
    VNC <-->|"RFB Protocol<br/>TCP :5900"| VNC_Server

    classDef proxy fill:#1a1a2e,stroke:#16213e,color:#e5e5e5
    classDef daemon fill:#0f3460,stroke:#533483,color:#e5e5e5
    classDef target fill:#1a1a2e,stroke:#e94560,color:#e5e5e5

    class Server,Tools proxy
    class CMD,Scale,VNC,Capture,Mouse,KB daemon
    class VNC_Server,Desktop target

レイヤー

レイヤー	言語	役割	通信方式
MCP Proxy	JavaScript (Node.js)	MCP プロトコル経由で Claude と通信し、デーモンのライフサイクルを管理します	stdio JSON-RPC
VNC Daemon	Swift/C (Apple Silicon)	VNC 接続、画面キャプチャ、マウス／キーボード入力の注入	stdin/stdout PC (NDJSON)

PC（Procedure Call）プロトコル

プロキシとデーモン間の通信には、NDJSON 上で PC プロトコルを使用します。

Request:      {"method":"<name>","params":{...},"id":<int|string>}
Response:     {"result":{...},"id":<int|string>}
Error:        {"error":{"code":<int>,"message":"..."},"id":<int|string>}
Notification: {"method":"<name>","params":{...}}

座標のスケーリング

VNC サーバーのネイティブ解像度は、--max-dimension（デフォルト：1280px）に収まるよう縮小されます。Claude はスケーリングされた座標をより一貫して扱えます。デーモンがバックグラウンドで変換を処理します。

Native:  4220 x 2568  (VNC server framebuffer)
Scaled:  1280 x 779   (what Claude sees and targets)

mouse_click(640, 400) → VNC receives (2110, 1284)

画面戦略

Claude は段階的な検証アプローチにより、トークンの消費を最小限に抑えます。

diff_check       →  changeDetected: true/false     ~5ms    (text only, no image)
detect_elements  →  OCR text + bounding boxes      ~50ms   (text only, no image)
cursor_crop      →  crop around cursor              ~50ms   (small image)
screenshot       →  full screen capture             ~200ms  (full image)

detect_elements は Apple Vision フレームワークを使用して、デバイス上で OCR を実行します。テキストの内容と、スケーリングされた空間でのバウンディングボックス座標を返すため、ビジョントークンを消費せずに正確なクリック位置を指定できます。

---

インストール

要件

• macOS（Apple Silicon / aarch64）
• Node.js（LTS）

デーモン

brew tap ARAS-Workspace/tap
brew install claude-kvm-daemon

メモ

claude-kvm-daemon は CI（GitHub Actions）経由でコンパイルされ、コード署名されます。ビルド出力は、Homebrew 配布用の .tar.gz アーカイブと、公証用の .dmg ディスクイメージの 2 つの形式でパッケージ化されます。同じワークフロー内で DMG が公証のために Apple のサーバーに送信されます。この処理は CI ログから追跡できます。公証済みの DMG は CI アーティファクトとして入手でき、アーカイブされた .tar.gz もリポジトリのリリースとして公開されます。Homebrew でのインストールでは、このリリースが使用されます。

• リリース · ソースコード
• LibVNC ビルド · LibVNC ブランチ
• Homebrew Tap

MCP の設定

プロジェクトディレクトリに .mcp.json ファイルを作成します。

{
  "mcpServers": {
    "claude-kvm": {
      "command": "npx",
      "args": ["-y", "claude-kvm"],
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_USERNAME": "user",
        "VNC_PASSWORD": "pass",
        "CLAUDE_KVM_DAEMON_PATH": "/opt/homebrew/bin/claude-kvm-daemon",
        "CLAUDE_KVM_DAEMON_PARAMETERS": "-v"
      }
    }
  }
}

メモ

このツールは CI 経由でエンドツーエンドテストされています。Claude が VNC 経由でタスクを実行し、その結果を独立したビジョンモデルが観察して検証します。実際のワークフロー実行、システムプロンプト、デモ録画については、統合テストを参照してください。

設定

MCP プロキシ（ENV）

パラメーター	デフォルト	説明
VNC_HOST	127.0.0.1	VNC サーバーのアドレス
VNC_PORT	5900	VNC ポート番号
VNC_USERNAME		ユーザー名（ARD では必須）
VNC_PASSWORD		パスワード
CLAUDE_KVM_DAEMON_PATH	claude-kvm-daemon	デーモンのバイナリパス（すでに PATH にある場合は不要）
CLAUDE_KVM_DAEMON_PARAMETERS		デーモンに渡す追加の CLI 引数

デーモンパラメーター（CLI）

CLAUDE_KVM_DAEMON_PARAMETERS を介してデーモンに渡す追加引数：

"CLAUDE_KVM_DAEMON_PARAMETERS": "--max-dimension 800 -v"

パラメーター	デフォルト	説明
--max-dimension	1280	ディスプレイの最大スケーリング寸法（px）
--connect-timeout		VNC 接続タイムアウト（秒）
--bits-per-sample		ピクセルサンプルあたりのビット数
--no-reconnect		自動再接続を無効にする
-v, --verbose		詳細ログ（stderr）

実行時設定（PC）

タイミングと表示に関するすべてのパラメーターは、configure メソッドで実行時に設定できます。現在の値を確認するには、get_timing を使用してください。

タイミングを設定します：

{"method":"configure","params":{"click_hold_ms":80,"key_hold_ms":50}}

{"result":{"detail":"OK — changed: click_hold_ms, key_hold_ms"}}

表示倍率を変更します：

{"method":"configure","params":{"max_dimension":960}}

{"result":{"detail":"OK — changed: max_dimension","scaledWidth":960,"scaledHeight":584}}

デフォルト値にリセットします：

{"method":"configure","params":{"reset":true}}

{"result":{"detail":"OK — reset to defaults","timing":{"click_hold_ms":50,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":30,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}

現在の値を取得します：

{"method":"get_timing"}

{"result":{"timing":{"click_hold_ms":80,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":50,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}

パラメーター	デフォルト	説明
max_dimension	1280	スクリーンショットの最大寸法
cursor_crop_radius	150	カーソル切り抜き半径（px）
click_hold_ms	50	クリックの押下時間
double_click_gap_ms	50	ダブルクリックの間隔
hover_settle_ms	400	ホバー後の安定待機時間
drag_position_ms	30	ドラッグ前の位置決め待機時間
drag_press_ms	50	ドラッグ時の押下しきい値
drag_step_ms	5	補間点間の時間
drag_settle_ms	30	ボタンを離す前の安定待機時間
drag_pixels_per_step	20	ピクセルあたりの点の密度
drag_min_steps	10	補間ステップの最小数
scroll_press_ms	10	スクロールの押下・解放間隔
scroll_tick_ms	20	ティック間の遅延
key_hold_ms	30	キーの押下時間
combo_mod_ms	10	修飾キーの安定待機時間
type_key_ms	20	入力中のキー押下時間
type_inter_key_ms	20	文字間の遅延
type_shift_ms	10	Shift キーの安定待機時間
paste_settle_ms	30	クリップボード書き込み後の待機時間

---

ツール

すべての操作は、単一の vnc_command ツールを通じて実行します：

画面

アクション	パラメーター	説明
screenshot		画面全体をPNG形式でキャプチャします
cursor_crop		十字線オーバーレイ付きでカーソル周辺を切り抜きます
diff_check		基準画像と比較して画面の変化を検出します
set_baseline		現在の画面を差分比較用の基準画像として保存します

マウス

アクション	パラメーター	説明
mouse_click	x, y, button?	クリック（left|right|middle）
mouse_double_click	x, y	ダブルクリック
mouse_move	x, y	カーソルを移動します
hover	x, y	カーソルを移動して安定を待ちます
nudge	dx, dy	カーソルを相対移動します
mouse_drag	x, y, toX, toY	始点から終点までドラッグします
scroll	x, y, direction, amount?	スクロール（up|down|left|right）

キーボード

アクション	パラメーター	説明
key_tap	key	単一キーを押します（enter|escape|tab|space|...）
key_combo	key または keys	修飾キーの組み合わせ（"cmd+c" または ["cmd","shift","3"]）
key_type	text	テキストを1文字ずつ入力します
paste	text	クリップボード経由でテキストを貼り付けます

検出

アクション	パラメーター	説明
detect_elements		バウンディングボックス付きのOCRテキスト検出（Apple Vision）

スケーリングされた座標空間のバウンディングボックス座標とともに、テキスト要素を返します。

{"method":"detect_elements"}

{"result":{"detail":"13 elements","elements":[{"confidence":1,"h":9,"text":"Finder","w":32,"x":37,"y":6},{"confidence":1,"h":9,"text":"File","w":15,"x":84,"y":6},{"confidence":1,"h":9,"text":"Edit","w":19,"x":112,"y":6},{"confidence":1,"h":9,"text":"View","w":22,"x":143,"y":6},{"confidence":1,"h":11,"text":"Go","w":15,"x":179,"y":6},{"confidence":1,"h":9,"text":"Window","w":35,"x":207,"y":6},{"confidence":1,"h":11,"text":"Help","w":22,"x":255,"y":6},{"confidence":1,"h":11,"text":"8•","w":26,"x":1161,"y":6},{"confidence":1,"h":9,"text":"Fri Feb 20 22:19","w":80,"x":1189,"y":6},{"confidence":1,"h":9,"text":"Assets","w":32,"x":1202,"y":97},{"confidence":1,"h":9,"text":"Passwords.kdbx","w":74,"x":1181,"y":168},{"confidence":1,"h":93,"text":"PHANTOM","w":633,"x":322,"y":477},{"confidence":1,"h":32,"text":"YOUR SERVER, YOUR NETWORK, YOUR PRIVACY","w":629,"x":325,"y":568}],"scaledHeight":717,"scaledWidth":1280}}

設定

アクション	パラメーター	説明
configure	{<params>}	実行時にタイミング／表示パラメーターを設定します
configure	{reset: true}	すべてのパラメーターをデフォルトにリセットします
get_timing		現在のタイミングと表示パラメーターを取得します

制御

アクション	パラメーター	説明
wait	ms?	待機します（デフォルトは500ms）
health		接続状態とディスプレイ情報を取得します
shutdown		デーモンを正常にシャットダウンします

---

認証

次のVNC認証方式に対応しています。

• VNC Auth — パスワードベースのチャレンジレスポンス認証（DES）
• ARD — Apple Remote Desktop（Diffie-Hellman + AES-128-ECB）

ARD認証タイプ30の認証情報リクエストを通じて、macOSを自動検出します。検出された場合、MetaキーはSuper（Commandキーとの互換性）に再マッピングされます。

---

メモ

ベアメタルのMacで実行していますか？VNCの強化、SSHトンネリング、セッションの安定性に関するヒントは、Mac M1 Preparation Tricksをご覧ください。

---

「Claude」はAnthropic, PBCの商標です。このプロジェクトはAnthropicと提携しておらず、同社から推奨も受けていません。

Copyright (c) 2026 Riza Emre ARAS — MIT License