Claude KVM
공식🤖 ⚡️ MCP 서버 ( MacOS) — VNC를 통해 원격 데스크톱 제어
문서
Claude KVM
원격 접속, 인공지능
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 설치는 이 릴리스를 추적합니다.
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 프록시 (환경 변수)
| 매개변수 | 기본값 | 설명 |
|---|---|---|
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 인증 — 비밀번호 기반 챌린지-응답 (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