Claude KVM
公式🤖 ⚡️ MCPサーバー（ MacOS）— VNC経由でリモートデスクトップを制御
ドキュメント
Claude KVM
リモートアクセス、人工知能
Claude KVMは、VNC経由でリモートデスクトップ環境を制御するMCPツールです。軽量なJSプロキシレイヤー（MCPサーバー）と、macOSシステム上で動作するプラットフォームネイティブのSwift VNCデーモンで構成されています。
[!TIP] Phantom-WG は優れた代替手段となり得ます。 自己ホスト型VPNのパフォーマンスを享受しながら、追加のプライバシー機能と共に、VNCサーバーを自身のネットワーク内に隔離できます。
ライブテスト実行
- 統合テスト
- Mac統合テスト
- Mac電卓テスト
- Mac関数電卓テスト
- Mac Safariブラウジングテスト
- Macドラッグ＆ドロップテスト
- Macチェステスト
- Macチェス直接テスト
- Mac Phantom-WGインストールテスト
[!NOTE] テストはGitHub Actions上で透過的に実施され、各ステップはCI環境で確認できます。統合テストの成否にかかわらず、各テストの最後には、エージェントがセッション中に実行した各ステップのスクリーンショットと、セッション全体を記録した
.mp4ビデオ録画が提供されます。これらの録画とスクリーンショットを確認することで、エージェントが各段階をどのように進めたか、タスクにかかった時間、システムプロンプトに基づいてどのような判断が下されたかを観察できます。自身の環境でMCPサーバー用のシステムプロンプトや指示を作成する際の参考として、これらの例を活用できます。
[!WARNING] これらの実行に添付されたアーティファクトは、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プロキシ | JavaScript (Node.js) | MCPプロトコルでClaudeと通信し、デーモンのライフサイクルを管理 | stdio JSON-RPC |
| VNCデーモン | Swift/C (Apple Silicon) | VNC接続、画面キャプチャ、マウス/キーボード入力の注入 | stdin/stdout PC (NDJSON) |
PC (プロシージャコール) プロトコル
プロキシとデーモン間の通信は、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は、オンデバイスOCRにApple Visionフレームワークを使用します。スケーリングされた空間でのバウンディングボックス座標と共にテキストコンテンツを返し、ビジョントークンを消費せずに正確なクリックターゲットを可能にします。
インストール
要件
- macOS (Apple Silicon / aarch64)
- Node.js (LTS)
デーモン
brew tap ARAS-Workspace/tap
brew install claude-kvm-daemon
[!NOTE]
claude-kvm-daemonはCI（GitHub Actions）経由でコンパイルおよびコード署名されます。ビルド出力は、Homebrew配布用の.tar.gzアーカイブと、公証用の.dmgディスクイメージの2つの形式でパッケージ化されます。DMGは同じワークフロー内でAppleサーバーに公証のために提出され、プロセスはCIログから追跡できます。公証済みDMGはCIアーティファクトとして利用可能です。アーカイブされた.tar.gzもリポジトリのリリースとして公開されます。Homebrewインストールはこのリリースを追跡します。
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"
}
}
}
}
[!NOTE] このツールは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 | シフトキー安定化 |
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)
macOSは、ARD認証タイプ30のクレデンシャルリクエストを介して自動検出されます。検出されると、MetaキーはSuper（Commandキー互換性）に再マッピングされます。
[!NOTE] ベアメタルのMacで実行していますか？VNCの強化、SSHトンネリング、セッション安定化のヒントについては、Mac M1準備のコツをご覧ください。
「Claude」はAnthropic, PBCの商標です。このプロジェクトはAnthropicとは提携しておらず、また承認も受けていません。
Copyright (c) 2026 Riza Emre ARAS — MIT License