Claude KVM

chính thức

🤖 ⚡️ Máy chủ MCP ( MacOS) — điều khiển máy tính từ xa qua VNC

Tài liệu

Claude KVM

Truy cập Từ xa, Trí tuệ Nhân tạo

Claude KVM là một công cụ MCP điều khiển môi trường máy tính từ xa qua VNC. Nó bao gồm một lớp proxy JS mỏng (máy chủ MCP) và một daemon VNC Swift gốc nền tảng chạy trên hệ thống macOS của bạn.

[!TIP] Phantom-WG có thể là một giải pháp thay thế tuyệt vời cho bạn. Cô lập máy chủ VNC của bạn trong mạng riêng của bạn trong khi tận hưởng hiệu suất VPN tự lưu trữ với các tính năng bảo mật bổ sung mà bạn có được.

Chạy Thử Trực tiếp

[!NOTE] Các kiểm thử được tiến hành minh bạch trên GitHub Actions — mỗi bước đều hiển thị trong môi trường CI. Vào cuối mỗi bài kiểm thử, dù tích hợp thành công hay thất bại, bạn sẽ tìm thấy ảnh chụp màn hình của từng bước mà tác nhân đã thực hiện trong phiên, cùng với bản ghi video .mp4 ghi lại toàn bộ phiên làm việc. Bằng cách xem lại các bản ghi và ảnh chụp màn hình này, bạn có thể quan sát cách tác nhân tiến triển qua từng giai đoạn, tác vụ mất bao lâu và những quyết định nào đã được đưa ra dựa trên lời nhắc hệ thống. Bạn có thể sử dụng các ví dụ này làm tham khảo khi tạo lời nhắc hệ thống hoặc hướng dẫn của riêng bạn cho máy chủ MCP trong môi trường của bạn.

[!WARNING] Các tạo phẩm đính kèm theo các lần chạy này có thể đã hết hạn do chính sách lưu giữ tạo phẩm của GitHub. Các bản sao lưu trữ được chuẩn bị qua quy trình làm việc Persist Artifacts và luôn có thể được truy cập bằng ID lần chạy từ thư mục artifacts/ trên nhánh press-kit.

Kiến trúc

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

Các Lớp

Lớp	Ngôn ngữ	Vai trò	Giao tiếp
MCP Proxy	JavaScript (Node.js)	Giao tiếp với Claude qua giao thức MCP, quản lý vòng đời daemon	stdio JSON-RPC
VNC Daemon	Swift/C (Apple Silicon)	Kết nối VNC, chụp màn hình, chèn đầu vào chuột/bàn phím	stdin/stdout PC (NDJSON)

Giao thức PC (Procedure Call)

Giao tiếp giữa proxy và daemon sử dụng giao thức PC qua 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":{...}}

Tỷ lệ Tọa độ

Độ phân giải gốc của máy chủ VNC được thu nhỏ để vừa với --max-dimension (mặc định: 1280px). Claude hoạt động nhất quán hơn với tọa độ đã được thu nhỏ — daemon xử lý việc chuyển đổi ở nền:

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

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

Chiến lược Màn hình

Claude giảm thiểu chi phí token bằng cách tiếp cận xác minh tiến triển:

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 sử dụng Apple Vision framework cho OCR trên thiết bị. Trả về nội dung văn bản với tọa độ hộp giới hạn trong không gian đã thu nhỏ — cho phép nhắm mục tiêu nhấp chuột chính xác mà không tiêu tốn token thị giác.

Cài đặt

Yêu cầu

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

Daemon

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

[!NOTE] claude-kvm-daemon được biên dịch và ký mã qua CI (GitHub Actions). Đầu ra bản dựng được đóng gói ở hai định dạng: một kho lưu trữ .tar.gz cho phân phối Homebrew và một ảnh đĩa .dmg để công chứng. DMG được gửi lên máy chủ Apple để công chứng trong cùng một quy trình làm việc — quá trình này có thể được theo dõi từ nhật ký CI. DMG đã công chứng có sẵn dưới dạng Tạo phẩm CI; .tar.gz đã lưu trữ cũng được xuất bản dưới dạng bản phát hành trên kho lưu trữ. Cài đặt Homebrew theo dõi bản phát hành này.

Bản phát hành · Mã nguồn

Bản dựng LibVNC · Nhánh LibVNC

Homebrew Tap

Cấu hình MCP

Tạo một tệp .mcp.json trong thư mục dự án của bạn:

{
  "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] Công cụ được kiểm thử đầu cuối qua CI — Claude thực thi các tác vụ qua VNC trong khi một mô hình thị giác độc lập quan sát và xác minh kết quả. Xem Kiểm thử Tích hợp để biết các lần chạy quy trình làm việc trực tiếp, lời nhắc hệ thống và bản ghi demo.

Cấu hình

MCP Proxy (ENV)

Tham số	Mặc định	Mô tả
`VNC_HOST`	`127.0.0.1`	Địa chỉ máy chủ VNC
`VNC_PORT`	`5900`	Số cổng VNC
`VNC_USERNAME`		Tên người dùng (bắt buộc cho ARD)
`VNC_PASSWORD`		Mật khẩu
`CLAUDE_KVM_DAEMON_PATH`	`claude-kvm-daemon`	Đường dẫn nhị phân daemon (không cần nếu đã có trong PATH)
`CLAUDE_KVM_DAEMON_PARAMETERS`		Đối số CLI bổ sung cho daemon

Tham số Daemon (CLI)

Các đối số bổ sung được truyền cho daemon qua CLAUDE_KVM_DAEMON_PARAMETERS:

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

Tham số	Mặc định	Mô tả
`--max-dimension`	`1280`	Kích thước thu nhỏ hiển thị tối đa (px)
`--connect-timeout`		Thời gian chờ kết nối VNC (giây)
`--bits-per-sample`		Mẫu bit trên mỗi điểm ảnh
`--no-reconnect`		Tắt tự động kết nối lại
`-v, --verbose`		Ghi nhật ký chi tiết (stderr)

Cấu hình Thời gian chạy (PC)

Tất cả các tham số thời gian và hiển thị đều có thể cấu hình trong thời gian chạy qua phương thức configure. Sử dụng get_timing để kiểm tra các giá trị hiện tại.

Đặt thời gian:

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

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

Thay đổi tỷ lệ hiển thị:

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

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

Đặt lại về mặc định:

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

Lấy giá trị hiện tại:

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

Tham số	Mặc định	Mô tả
`max_dimension`	`1280`	Kích thước ảnh chụp màn hình tối đa
`cursor_crop_radius`	`150`	Bán kính cắt con trỏ (px)
`click_hold_ms`	`50`	Thời lượng giữ nhấp chuột
`double_click_gap_ms`	`50`	Độ trễ khoảng cách nhấp đúp
`hover_settle_ms`	`400`	Thời gian chờ ổn định di chuột
`drag_position_ms`	`30`	Thời gian chờ vị trí trước khi kéo
`drag_press_ms`	`50`	Ngưỡng giữ nhấn kéo
`drag_step_ms`	`5`	Giữa các điểm nội suy
`drag_settle_ms`	`30`	Ổn định trước khi thả
`drag_pixels_per_step`	`20`	Mật độ điểm trên mỗi pixel
`drag_min_steps`	`10`	Số bước nội suy tối thiểu
`scroll_press_ms`	`10`	Khoảng cách nhấn-thả cuộn
`scroll_tick_ms`	`20`	Độ trễ giữa các tick
`key_hold_ms`	`30`	Thời lượng giữ phím
`combo_mod_ms`	`10`	Độ trễ ổn định phím bổ trợ
`type_key_ms`	`20`	Giữ phím trong khi gõ
`type_inter_key_ms`	`20`	Độ trễ giữa các ký tự
`type_shift_ms`	`10`	Ổn định phím shift
`paste_settle_ms`	`30`	Chờ sau khi ghi clipboard

Công cụ

Tất cả các thao tác được thực hiện thông qua một công cụ vnc_command duy nhất:

Màn hình

Hành động	Tham số	Mô tả
`screenshot`		Chụp toàn màn hình PNG
`cursor_crop`		Cắt xung quanh con trỏ với lớp phủ tâm ngắm
`diff_check`		Phát hiện thay đổi màn hình so với đường cơ sở
`set_baseline`		Lưu màn hình hiện tại làm tham chiếu khác biệt

Chuột

Hành động	Tham số	Mô tả
`mouse_click`	`x, y, button?`	Nhấp (trái\|phải\|giữa)
`mouse_double_click`	`x, y`	Nhấp đúp
`mouse_move`	`x, y`	Di chuyển con trỏ
`hover`	`x, y`	Di chuyển + chờ ổn định
`nudge`	`dx, dy`	Di chuyển con trỏ tương đối
`mouse_drag`	`x, y, toX, toY`	Kéo từ điểm bắt đầu đến kết thúc
`scroll`	`x, y, direction, amount?`	Cuộn (lên\|xuống\|trái\|phải)

Bàn phím

Hành động	Tham số	Mô tả
`key_tap`	`key`	Nhấn phím đơn (enter\|escape\|tab\|space\|...)
`key_combo`	`key` hoặc `keys`	Tổ hợp phím bổ trợ ("cmd+c" hoặc ["cmd","shift","3"])
`key_type`	`text`	Gõ văn bản từng ký tự
`paste`	`text`	Dán văn bản qua clipboard

Phát hiện

Hành động	Tham số	Mô tả
`detect_elements`		Phát hiện văn bản OCR với hộp giới hạn (Apple Vision)

Trả về các phần tử văn bản với tọa độ hộp giới hạn trong không gian đã thu nhỏ:

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

Cấu hình

Hành động	Tham số	Mô tả
`configure`	`{<params>}`	Đặt tham số thời gian/hiển thị khi chạy
`configure`	`{reset: true}`	Đặt lại tất cả tham số về mặc định
`get_timing`		Lấy tham số thời gian + hiển thị hiện tại

Điều khiển

Hành động	Tham số	Mô tả
`wait`	`ms?`	Chờ (mặc định 500ms)
`health`		Trạng thái kết nối + thông tin hiển thị
`shutdown`		Tắt daemon một cách nhẹ nhàng

Xác thực

Các phương thức xác thực VNC được hỗ trợ:

VNC Auth — thử thách-phản hồi dựa trên mật khẩu (DES)
ARD — Apple Remote Desktop (Diffie-Hellman + AES-128-ECB)

macOS được tự động phát hiện qua yêu cầu thông tin xác thực loại 30 của ARD. Khi được phát hiện, các phím Meta được ánh xạ lại thành Super (tương thích phím Command).

[!NOTE] Đang chạy trên máy Mac kim loại trần? Xem Mẹo chuẩn bị Mac M1 để biết các mẹo tăng cường bảo mật VNC, đường hầm SSH và ổn định phiên làm việc.

"Claude" là nhãn hiệu của Anthropic, PBC. Dự án này không liên kết hoặc được xác nhận bởi Anthropic.