Claude KVM

resmi

🤖 ⚡️ MCP sunucusu ( MacOS) — VNC üzerinden uzak masaüstlerini kontrol edin

Dokümantasyon

Claude KVM

Uzaktan Erişim, Yapay Zeka

Claude KVM, VNC üzerinden uzak masaüstü ortamlarını kontrol eden bir MCP aracıdır. İnce bir JS proxy katmanı (MCP sunucusu) ve macOS sisteminizde çalışan platforma özgü bir Swift VNC arka plan sürecinden oluşur.

[!TIP] Phantom-WG sizin için harika bir alternatif olabilir. VNC sunucunuzu kendi ağınızda yalıtırken, kendi barındırdığınız VPN performansının ve yol boyunca kazandığınız ek gizlilik özelliklerinin keyfini çıkarın.

Canlı Test Çalışmaları

[!NOTE] Testler GitHub Actions üzerinde şeffaf bir şekilde yürütülür — her adım CI ortamında görünür. Entegrasyon başarılı olsun ya da olmasın, her testin sonunda, ajanın oturum sırasında attığı her adımın ekran görüntülerini ve tüm oturumu yakalayan bir .mp4 video kaydını bulacaksınız. Bu kayıtları ve ekran görüntülerini inceleyerek, ajanın her aşamada nasıl ilerlediğini, görevin ne kadar sürdüğünü ve sistem istemine dayanarak hangi kararların alındığını gözlemleyebilirsiniz. Bu örnekleri, kendi ortamınızda MCP sunucusu için kendi sistem istemlerinizi veya talimatlarınızı oluştururken referans olarak kullanabilirsiniz.

[!WARNING] Bu çalışmalara eklenen yapıtlar, GitHub'ın yapıt saklama politikası nedeniyle süresi dolmuş olabilir. Kalıcı kopyalar Yapıtları Kalıcılaştır iş akışı aracılığıyla hazırlanır ve press-kit dalındaki artifacts/ dizininden çalışma kimliği ile her zaman erişilebilir.

Mimari

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

Katmanlar

Katman	Dil	Rol	İletişim
MCP Proxy	JavaScript (Node.js)	MCP protokolü üzerinden Claude ile iletişim kurar, arka plan süreci yaşam döngüsünü yönetir	stdio JSON-RPC
VNC Arka Plan Süreci	Swift/C (Apple Silicon)	VNC bağlantısı, ekran yakalama, fare/klavye girişi enjeksiyonu	stdin/stdout PC (NDJSON)

PC (Prosedür Çağrısı) Protokolü

Proxy ve arka plan süreci arasındaki iletişim, NDJSON üzerinden PC protokolünü kullanır:

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

Koordinat Ölçeklendirme

VNC sunucusunun doğal çözünürlüğü, --max-dimension (varsayılan: 1280px) içine sığacak şekilde küçültülür. Claude, ölçeklendirilmiş koordinatlarla daha tutarlı çalışır — arka plan süreci dönüşümü arka planda halleder:

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

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

Ekran Stratejisi

Claude, aşamalı bir doğrulama yaklaşımıyla token maliyetini en aza indirir:

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, cihaz üzerinde OCR için Apple Vision çerçevesini kullanır. Ölçeklendirilmiş alanda sınırlayıcı kutu koordinatlarıyla metin içeriğini döndürür — görüntü token'ları tüketmeden hassas tıklama hedeflemesi sağlar.

Kurulum

Gereksinimler

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

Arka Plan Süreci

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

[!NOTE] claude-kvm-daemon, CI (GitHub Actions) aracılığıyla derlenir ve kod imzalanır. Derleme çıktısı iki biçimde paketlenir: Homebrew dağıtımı için bir .tar.gz arşivi ve noter onayı için bir .dmg disk imajı. DMG, aynı iş akışı içinde Apple sunucularına noter onayı için gönderilir — süreç CI günlüklerinden izlenebilir. Noter onaylı DMG bir CI Yapıtı olarak mevcuttur; arşivlenmiş .tar.gz ayrıca depoda bir sürüm olarak yayınlanır. Homebrew kurulumu bu sürümü izler.

Sürüm · Kaynak Kodu

LibVNC Derlemesi · LibVNC Dalı

Homebrew Tap

MCP Yapılandırması

Proje dizininizde bir .mcp.json dosyası oluşturun:

{
  "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] Araç, CI aracılığıyla uçtan uca test edilir — Claude VNC üzerinden görevleri yürütürken bağımsız bir görüntü modeli sonuçları gözlemler ve doğrular. Canlı iş akışı çalışmaları, sistem istemleri ve demo kayıtları için Entegrasyon Testi sayfasına bakın.

Yapılandırma

MCP Proxy (ENV)

Parametre	Varsayılan	Açıklama
`VNC_HOST`	`127.0.0.1`	VNC sunucu adresi
`VNC_PORT`	`5900`	VNC port numarası
`VNC_USERNAME`		Kullanıcı adı (ARD için gerekli)
`VNC_PASSWORD`		Parola
`CLAUDE_KVM_DAEMON_PATH`	`claude-kvm-daemon`	Arka plan süreci ikili dosya yolu (PATH'te zaten varsa gerekmez)
`CLAUDE_KVM_DAEMON_PARAMETERS`		Arka plan süreci için ek CLI argümanları

Arka Plan Süreci Parametreleri (CLI)

CLAUDE_KVM_DAEMON_PARAMETERS aracılığıyla arka plan sürecine iletilen ek argümanlar:

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

Parametre	Varsayılan	Açıklama
`--max-dimension`	`1280`	Maksimum ekran ölçeklendirme boyutu (px)
`--connect-timeout`		VNC bağlantı zaman aşımı (saniye)
`--bits-per-sample`		Piksel başına bit örneği
`--no-reconnect`		Otomatik yeniden bağlanmayı devre dışı bırak
`-v, --verbose`		Ayrıntılı günlükleme (stderr)

Çalışma Zamanı Yapılandırması (PC)

Tüm zamanlama ve ekran parametreleri, configure yöntemi aracılığıyla çalışma zamanında yapılandırılabilir. Mevcut değerleri incelemek için get_timing kullanın.

Zamanlamayı ayarla:

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

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

Ekran ölçeklendirmeyi değiştir:

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

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

Varsayılanlara sıfırla:

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

Mevcut değerleri al:

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

Parametre	Varsayılan	Açıklama
`max_dimension`	`1280`	Maksimum ekran görüntüsü boyutu
`cursor_crop_radius`	`150`	İmleç kırpma yarıçapı (px)
`click_hold_ms`	`50`	Tıklama basılı tutma süresi
`double_click_gap_ms`	`50`	Çift tıklama aralığı gecikmesi
`hover_settle_ms`	`400`	Üzerinde durma bekleme süresi
`drag_position_ms`	`30`	Sürükleme öncesi konum bekleme
`drag_press_ms`	`50`	Sürükleme basma eşiği
`drag_step_ms`	`5`	Ara değer noktaları arası
`drag_settle_ms`	`30`	Bırakma öncesi yerleşme
`drag_pixels_per_step`	`20`	Piksel başına nokta yoğunluğu
`drag_min_steps`	`10`	Minimum ara değer adımı
`scroll_press_ms`	`10`	Kaydırma basma-bırakma aralığı
`scroll_tick_ms`	`20`	Tikler arası gecikme
`key_hold_ms`	`30`	Tuş basılı tutma süresi
`combo_mod_ms`	`10`	Değiştirici yerleşme gecikmesi
`type_key_ms`	`20`	Yazma sırasında tuş basılı tutma
`type_inter_key_ms`	`20`	Karakterler arası gecikme
`type_shift_ms`	`10`	Shift tuşu yerleşme
`paste_settle_ms`	`30`	Pano yazma sonrası bekleme

Araçlar

Tüm işlemler tek bir vnc_command aracı üzerinden gerçekleştirilir:

Ekran

Eylem	Parametreler	Açıklama
`screenshot`		Tam ekran PNG yakalama
`cursor_crop`		Artı işareti kaplamasıyla imleç etrafını kırp
`diff_check`		Referansa göre ekran değişikliklerini tespit et
`set_baseline`		Mevcut ekranı fark referansı olarak kaydet

Fare

Eylem	Parametreler	Açıklama
`mouse_click`	`x, y, button?`	Tıklama (sol\|sağ\|orta)
`mouse_double_click`	`x, y`	Çift tıklama
`mouse_move`	`x, y`	İmleci taşı
`hover`	`x, y`	Taşı + yerleşme beklemesi
`nudge`	`dx, dy`	Göreceli imleç hareketi
`mouse_drag`	`x, y, toX, toY`	Başlangıçtan bitişe sürükle
`scroll`	`x, y, direction, amount?`	Kaydırma (yukarı\|aşağı\|sol\|sağ)

Klavye

Eylem	Parametreler	Açıklama
`key_tap`	`key`	Tek tuş basımı (enter\|escape\|tab\|space\|...)
`key_combo`	`key` veya `keys`	Değiştirici kombinasyonu ("cmd+c" veya ["cmd","shift","3"])
`key_type`	`text`	Metni karakter karakter yaz
`paste`	`text`	Metni pano aracılığıyla yapıştır

Algılama

Eylem	Parametreler	Açıklama
`detect_elements`		Sınırlayıcı kutularla OCR metin algılama (Apple Vision)

Ölçeklendirilmiş alanda sınırlayıcı kutu koordinatlarıyla metin öğelerini döndürür:

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

Yapılandırma

Eylem	Parametreler	Açıklama
`configure`	`{<params>}`	Çalışma zamanında zamanlama/ekran parametrelerini ayarla
`configure`	`{reset: true}`	Tüm parametreleri varsayılanlara sıfırla
`get_timing`		Mevcut zamanlama + ekran parametrelerini al

Kontrol

Eylem	Parametreler	Açıklama
`wait`	`ms?`	Bekle (varsayılan 500ms)
`health`		Bağlantı durumu + ekran bilgisi
`shutdown`		Arka plan sürecini düzgün kapat

Kimlik Doğrulama

Desteklenen VNC kimlik doğrulama yöntemleri:

VNC Auth — parola tabanlı meydan okuma-yanıt (DES)
ARD — Apple Remote Desktop (Diffie-Hellman + AES-128-ECB)

macOS, ARD auth tip 30 kimlik bilgisi isteği aracılığıyla otomatik olarak algılanır. Algılandığında, Meta tuşları Super olarak yeniden eşlenir (Command tuşu uyumluluğu).

[!NOTE] Çıplak metal bir Mac'te mi çalışıyorsunuz? VNC sağlamlaştırma, SSH tünelleme ve oturum kararlılığı ipuçları için Mac M1 Hazırlık Püf Noktaları sayfasına bakın.

"Claude", Anthropic, PBC'nin ticari markasıdır. Bu proje Anthropic ile bağlantılı değildir veya onaylanmamıştır.