Claude KVM

Claude KVM

원격 접근, 인공지능

claude-kvm.ai

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의 아티팩트 보존 정책으로 인해 이 실행에 첨부된 아티팩트가 만료되었을 수 있습니다. 영구 사본은 아티팩트 보존 워크플로우를 통해 준비되며, 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 디스크 이미지의 두 가지 형식으로 패키징됩니다. 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] 이 도구는 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	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 인증 유형 30 자격 증명 요청을 통해 자동 감지됩니다. 감지되면 Meta 키가 Super로 다시 매핑됩니다(Command 키 호환성).

---

[!NOTE] 베어메탈 Mac에서 실행 중이신가요? VNC 강화, SSH 터널링, 세션 안정성 팁은 Mac M1 준비 요령을 참조하세요.

---

"Claude"는 Anthropic, PBC의 상표입니다. 이 프로젝트는 Anthropic과 제휴하거나 승인받지 않았습니다.

Copyright (c) 2026 Riza Emre ARAS — MIT License