Claude KVM

resmi

🤖 ⚡️ MCP server

Dokumentasi

Claude KVM

Akses Jarak Jauh, Kecerdasan Buatan

Claude KVM adalah alat MCP yang mengendalikan lingkungan desktop jarak jauh melalui VNC. Alat ini terdiri dari lapisan proksi JS tipis (server MCP) dan daemon VNC Swift asli platform yang berjalan di sistem macOS Anda.

[!TIP] Phantom-WG bisa menjadi alternatif yang bagus untuk Anda. Isolasi server VNC Anda dalam jaringan Anda sendiri sambil menikmati performa VPN self-hosted dengan fitur privasi tambahan yang Anda dapatkan.

Uji Coba Langsung

[!NOTE] Pengujian dilakukan secara transparan di GitHub Actions — setiap langkah terlihat di lingkungan CI. Di akhir setiap pengujian, baik integrasi berhasil atau gagal, Anda akan menemukan tangkapan layar dari setiap langkah yang diambil agen selama sesi, bersama dengan rekaman video .mp4 yang merekam seluruh sesi. Dengan meninjau rekaman dan tangkapan layar ini, Anda dapat mengamati bagaimana agen berkembang melalui setiap tahap, berapa lama tugas berlangsung, dan keputusan apa yang dibuat berdasarkan prompt sistem. Anda dapat menggunakan contoh-contoh ini sebagai referensi saat menyusun prompt sistem atau instruksi Anda sendiri untuk server MCP di lingkungan Anda sendiri.

[!WARNING] Artefak yang dilampirkan pada proses ini mungkin telah kedaluwarsa karena kebijakan retensi artefak GitHub. Salinan persisten disiapkan melalui alur kerja Persist Artifacts dan selalu dapat diakses berdasarkan ID proses dari direktori artifacts/ di cabang press-kit.

Arsitektur

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

Lapisan

Lapisan	Bahasa	Peran	Komunikasi
Proksi MCP	JavaScript (Node.js)	Berkomunikasi dengan Claude melalui protokol MCP, mengelola siklus hidup daemon	stdio JSON-RPC
Daemon VNC	Swift/C (Apple Silicon)	Koneksi VNC, tangkapan layar, injeksi input mouse/keyboard	stdin/stdout PC (NDJSON)

Protokol PC (Panggilan Prosedur)

Komunikasi antara proksi dan daemon menggunakan protokol PC melalui NDJSON:

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

Penskalaan Koordinat

Resolusi asli server VNC diperkecil agar sesuai dengan --max-dimension (default: 1280px). Claude bekerja lebih konsisten dengan koordinat yang diskalakan — daemon menangani konversi di latar belakang:

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

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

Strategi Layar

Claude meminimalkan biaya token dengan pendekatan verifikasi progresif:

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 menggunakan kerangka Apple Vision untuk OCR pada perangkat. Mengembalikan konten teks dengan koordinat kotak pembatas dalam ruang yang diskalakan — memungkinkan penargetan klik yang tepat tanpa menghabiskan token visi.

Instalasi

Persyaratan

macOS (Apple Silicon / aarch64)
Node.js (LTS)

Daemon

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

[!NOTE] claude-kvm-daemon dikompilasi dan ditandatangani kode melalui CI (GitHub Actions). Output build dikemas dalam dua format: arsip .tar.gz untuk distribusi Homebrew dan image disk .dmg untuk notarisasi. DMG dikirimkan ke server Apple untuk notarisasi dalam alur kerja yang sama — prosesnya dapat dilacak dari log CI. DMG yang dinotarisasi tersedia sebagai Artefak CI; .tar.gz yang diarsipkan juga diterbitkan sebagai rilis di repositori. Instalasi Homebrew melacak rilis ini.

Rilis · Kode Sumber

Build LibVNC · Cabang LibVNC

Homebrew Tap

Konfigurasi MCP

Buat file .mcp.json di direktori proyek Anda:

{
  "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] Alat ini diuji end-to-end melalui CI — Claude menjalankan tugas melalui VNC sementara model visi independen mengamati dan memverifikasi hasilnya. Lihat Uji Integrasi untuk proses alur kerja langsung, prompt sistem, dan rekaman demo.

Konfigurasi

Proksi MCP (ENV)

Parameter	Default	Deskripsi
`VNC_HOST`	`127.0.0.1`	Alamat server VNC
`VNC_PORT`	`5900`	Nomor port VNC
`VNC_USERNAME`		Nama pengguna (diperlukan untuk ARD)
`VNC_PASSWORD`		Kata sandi
`CLAUDE_KVM_DAEMON_PATH`	`claude-kvm-daemon`	Jalur biner daemon (tidak diperlukan jika sudah ada di PATH)
`CLAUDE_KVM_DAEMON_PARAMETERS`		Argumen CLI tambahan untuk daemon

Parameter Daemon (CLI)

Argumen tambahan yang diteruskan ke daemon melalui CLAUDE_KVM_DAEMON_PARAMETERS:

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

Parameter	Default	Deskripsi
`--max-dimension`	`1280`	Dimensi penskalaan tampilan maksimum (px)
`--connect-timeout`		Batas waktu koneksi VNC (detik)
`--bits-per-sample`		Bit per sampel piksel
`--no-reconnect`		Nonaktifkan koneksi ulang otomatis
`-v, --verbose`		Log verbose (stderr)

Konfigurasi Runtime (PC)

Semua parameter waktu dan tampilan dapat dikonfigurasi saat runtime melalui metode configure. Gunakan get_timing untuk memeriksa nilai saat ini.

Atur waktu:

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

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

Ubah penskalaan tampilan:

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

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

Atur ulang ke default:

{"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}}

Dapatkan nilai saat ini:

{"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}}

Parameter	Default	Deskripsi
`max_dimension`	`1280`	Dimensi tangkapan layar maks
`cursor_crop_radius`	`150`	Radius potong kursor (px)
`click_hold_ms`	`50`	Durasi tahan klik
`double_click_gap_ms`	`50`	Jeda jeda klik ganda
`hover_settle_ms`	`400`	Tunggu hover settle
`drag_position_ms`	`30`	Tunggu posisi pra-seret
`drag_press_ms`	`50`	Ambang tahan tekan seret
`drag_step_ms`	`5`	Antara titik interpolasi
`drag_settle_ms`	`30`	Settle sebelum lepas
`drag_pixels_per_step`	`20`	Kepadatan titik per piksel
`drag_min_steps`	`10`	Langkah interpolasi min
`scroll_press_ms`	`10`	Jeda tekan-lepas gulir
`scroll_tick_ms`	`20`	Jeda antar-tik
`key_hold_ms`	`30`	Durasi tahan tombol
`combo_mod_ms`	`10`	Jeda settle pengubah
`type_key_ms`	`20`	Tahan tombol saat mengetik
`type_inter_key_ms`	`20`	Jeda antar-karakter
`type_shift_ms`	`10`	Settle tombol shift
`paste_settle_ms`	`30`	Tunggu pasca-tulis papan klip

Alat

Semua operasi dilakukan melalui satu alat vnc_command:

Layar

Aksi	Parameter	Deskripsi
`screenshot`		Tangkapan layar penuh PNG
`cursor_crop`		Potong di sekitar kursor dengan overlay crosshair
`diff_check`		Deteksi perubahan layar terhadap baseline
`set_baseline`		Simpan layar saat ini sebagai referensi diff

Mouse

Aksi	Parameter	Deskripsi
`mouse_click`	`x, y, button?`	Klik (kiri\|kanan\|tengah)
`mouse_double_click`	`x, y`	Klik ganda
`mouse_move`	`x, y`	Pindahkan kursor
`hover`	`x, y`	Pindahkan + tunggu settle
`nudge`	`dx, dy`	Pergerakan kursor relatif
`mouse_drag`	`x, y, toX, toY`	Seret dari awal ke akhir
`scroll`	`x, y, direction, amount?`	Gulir (atas\|bawah\|kiri\|kanan)

Keyboard

Aksi	Parameter	Deskripsi
`key_tap`	`key`	Tekan tombol tunggal (enter\|escape\|tab\|spasi\|...)
`key_combo`	`key` atau `keys`	Kombo pengubah ("cmd+c" atau ["cmd","shift","3"])
`key_type`	`text`	Ketik teks karakter demi karakter
`paste`	`text`	Tempel teks melalui papan klip

Deteksi

Aksi	Parameter	Deskripsi
`detect_elements`		Deteksi teks OCR dengan kotak pembatas (Apple Vision)

Mengembalikan elemen teks dengan koordinat kotak pembatas dalam ruang yang diskalakan:

{"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}}

Konfigurasi

Aksi	Parameter	Deskripsi
`configure`	`{<params>}`	Atur parameter waktu/tampilan saat runtime
`configure`	`{reset: true}`	Atur ulang semua parameter ke default
`get_timing`		Dapatkan parameter waktu + tampilan saat ini

Kontrol

Aksi	Parameter	Deskripsi
`wait`	`ms?`	Tunggu (default 500ms)
`health`		Status koneksi + info tampilan
`shutdown`		Matikan daemon dengan anggun

Autentikasi

Metode autentikasi VNC yang didukung:

VNC Auth — challenge-response berbasis kata sandi (DES)
ARD — Apple Remote Desktop (Diffie-Hellman + AES-128-ECB)

macOS terdeteksi otomatis melalui permintaan kredensial ARD tipe auth 30. Saat terdeteksi, tombol Meta dipetakan ulang ke Super (kompatibilitas tombol Command).

[!NOTE] Berjalan di Mac bare-metal? Lihat Trik Persiapan Mac M1 untuk pengamanan VNC, tunneling SSH, dan tips stabilitas sesi.

"Claude" adalah merek dagang dari Anthropic, PBC. Proyek ini tidak berafiliasi dengan atau didukung oleh Anthropic.