Claude KVM

ทางการ

🤖 ⚡️ เซิร์ฟเวอร์ MCP ( MacOS) — ควบคุมเดสก์ท็อประยะไกลผ่าน VNC

เอกสาร

Claude KVM

การเข้าถึงระยะไกล, ปัญญาประดิษฐ์

Claude KVM เป็นเครื่องมือ MCP ที่ควบคุมสภาพแวดล้อมเดสก์ท็อประยะไกลผ่าน VNC ประกอบด้วยเลเยอร์พร็อกซี JS แบบบาง (เซิร์ฟเวอร์ MCP) และดีมอน VNC แบบเนทีฟของแพลตฟอร์มที่เขียนด้วย Swift ซึ่งทำงานบนระบบ macOS ของคุณ

[!TIP] Phantom-WG อาจเป็นทางเลือกที่ยอดเยี่ยมสำหรับคุณ แยกเซิร์ฟเวอร์ VNC ของคุณภายในเครือข่ายของคุณเอง พร้อมเพลิดเพลินกับประสิทธิภาพ VPN แบบโฮสต์เอง พร้อมคุณสมบัติความเป็นส่วนตัวเพิ่มเติมที่คุณได้รับ

การทดสอบรันสด

[!NOTE] การทดสอบดำเนินการอย่างโปร่งใสบน GitHub Actions — แต่ละขั้นตอนสามารถมองเห็นได้ในสภาพแวดล้อม CI เมื่อสิ้นสุดการทดสอบทุกครั้ง ไม่ว่าการรวมระบบจะผ่านหรือไม่ผ่าน คุณจะพบภาพหน้าจอของแต่ละขั้นตอนที่เอเจนต์ดำเนินการระหว่างเซสชัน พร้อมกับการบันทึกวิดีโอ .mp4 ที่บันทึกเซสชันทั้งหมด โดยการตรวจสอบการบันทึกและภาพหน้าจอเหล่านี้ คุณสามารถสังเกตได้ว่าเอเจนต์ดำเนินการผ่านแต่ละขั้นตอนอย่างไร งานใช้เวลานานเท่าใด และมีการตัดสินใจใดบ้างตามพรอมต์ของระบบ คุณสามารถใช้ตัวอย่างเหล่านี้เป็นข้อมูลอ้างอิงเมื่อสร้างพรอมต์หรือคำแนะนำระบบของคุณเองสำหรับเซิร์ฟเวอร์ MCP ในสภาพแวดล้อมของคุณเอง

[!WARNING] อาร์ติแฟกต์ที่แนบมากับการรันเหล่านี้อาจหมดอายุเนื่องจากนโยบายการเก็บรักษาอาร์ติแฟกต์ของ GitHub สำเนาถาวรถูกจัดเตรียมผ่านเวิร์กโฟลว์ Persist Artifacts และสามารถเข้าถึงได้เสมอด้วยรันไอดีจากไดเรกทอรี artifacts/ บนสาขา press-kit

สถาปัตยกรรม

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)	สื่อสารกับ Claude ผ่านโปรโตคอล MCP จัดการวงจรชีวิตของดีมอน	stdio JSON-RPC
VNC Daemon	Swift/C (Apple Silicon)	การเชื่อมต่อ VNC, การจับภาพหน้าจอ, การฉีดอินพุตเมาส์/คีย์บอร์ด	stdin/stdout PC (NDJSON)

โปรโตคอล PC (Procedure Call)

การสื่อสารระหว่างพร็อกซีและดีมอนใช้โปรโตคอล PC ผ่าน 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":{...}}

การปรับขนาดพิกัด

ความละเอียดดั้งเดิมของเซิร์ฟเวอร์ 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

[!NOTE] claude-kvm-daemon ถูกคอมไพล์และลงนามโค้ดผ่าน CI (GitHub Actions) เอาต์พุตบิลด์ถูกบรรจุในสองรูปแบบ: ไฟล์เก็บถาวร .tar.gz สำหรับการแจกจ่าย Homebrew และอิมเมจดิสก์ .dmg สำหรับการรับรองเอกสาร 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"
      }
    }
  }
}

[!NOTE] เครื่องมือนี้ถูกทดสอบแบบ end-to-end ผ่าน CI — Claude ดำเนินงานผ่าน VNC ในขณะที่โมเดลการมองเห็นอิสระสังเกตและตรวจสอบผลลัพธ์ ดู การทดสอบการรวมระบบ สำหรับการรันเวิร์กโฟลว์สด พรอมต์ระบบ และการบันทึกเดโม

การกำหนดค่า

MCP Proxy (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`		บันทึกหน้าจอปัจจุบันเป็นข้อมูลอ้างอิง diff

เมาส์

การกระทำ	พารามิเตอร์	คำอธิบาย
`mouse_click`	`x, y, button?`	คลิก (ซ้าย\|ขวา\|กลาง)
`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?`	เลื่อน (ขึ้น\|ลง\|ซ้าย\|ขวา)

คีย์บอร์ด

การกระทำ	พารามิเตอร์	คำอธิบาย
`key_tap`	`key`	กดปุ่มเดี่ยว (enter\|escape\|tab\|space\|...)
`key_combo`	`key` หรือ `keys`	คอมโบโมดิฟายเออร์ ("cmd+c" หรือ ["cmd","shift","3"])
`key_type`	`text`	พิมพ์ข้อความทีละอักขระ
`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 auth 30 เมื่อตรวจพบ ปุ่ม Meta จะถูกแมปใหม่เป็น Super (ความเข้ากันได้ของปุ่ม Command)

[!NOTE] กำลังรันบน Mac แบบ bare-metal อยู่ใช่ไหม? ดู เคล็ดลับการเตรียม Mac M1 สำหรับการเสริมความปลอดภัย VNC, การทำ SSH tunneling และเคล็ดลับความเสถียรของเซสชัน

"Claude" เป็นเครื่องหมายการค้าของ Anthropic, PBC โปรเจกต์นี้ไม่ได้มีส่วนเกี่ยวข้องหรือได้รับการรับรองจาก Anthropic