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 и всегда доступны по ID запуска из директории 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 для распознавания текста на устройстве. Возвращает текстовое содержимое с координатами ограничивающих рамок в масштабированном пространстве — позволяет точно нацеливать клики без расхода токенов зрения.

Установка

Требования

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] Инструмент проходит сквозное тестирование через 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`		Сохранить текущий экран как эталон для сравнения

Мышь

Действие	Параметры	Описание
`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`		Обнаружение текста с ограничивающими рамками (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?`	Ожидание (по умолчанию 500 мс)
`health`		Статус подключения + информация о дисплее
`shutdown`		Корректное завершение работы демона

Аутентификация

Поддерживаемые методы аутентификации VNC:

VNC Auth — аутентификация по паролю с запросом-ответом (DES)
ARD — Apple Remote Desktop (Диффи-Хеллман + AES-128-ECB)

macOS автоматически определяется по запросу учетных данных типа 30 для ARD. При обнаружении клавиши Meta переназначаются на Super (совместимость с клавишей Command).

[!NOTE] Запускаете на голом железе Mac? См. Mac M1 Preparation Tricks — советы по усилению VNC, SSH-туннелированию и стабильности сеанса.

«Claude» является торговой маркой Anthropic, PBC. Этот проект не связан с Anthropic и не одобрен ею.