Claude KVM MCP Server

oficial

🤖 ⚡️ Servidor MCP ( MacOS) — controle áreas de trabalho remotas via VNC

Documentação

Claude KVM

Acesso Remoto, Inteligência Artificial

Claude KVM é uma ferramenta MCP que controla ambientes de desktop remotos via VNC. Consiste em uma fina camada de proxy JS (servidor MCP) e um daemon VNC nativo em Swift rodando no seu sistema macOS.

[!TIP] Phantom-WG pode ser uma ótima alternativa para você. Isole seu servidor VNC dentro da sua própria rede enquanto desfruta do desempenho de VPN auto-hospedada com os recursos extras de privacidade que você ganha ao longo do caminho.

Testes ao Vivo

[!NOTE] Os testes são conduzidos de forma transparente no GitHub Actions — cada etapa é visível no ambiente de CI. Ao final de cada teste, seja a integração bem-sucedida ou não, você encontrará capturas de tela de cada etapa que o agente realizou durante a sessão, juntamente com uma gravação de vídeo .mp4 que captura toda a sessão. Ao revisar essas gravações e capturas de tela, você pode observar como o agente progrediu em cada estágio, quanto tempo a tarefa levou e quais decisões foram tomadas com base no prompt do sistema. Você pode usar esses exemplos como referência ao criar seus próprios prompts de sistema ou instruções para o servidor MCP em seu próprio ambiente.

[!WARNING] Os artefatos anexados a essas execuções podem ter expirado devido à política de retenção de artefatos do GitHub. Cópias persistentes são preparadas através do fluxo de trabalho Persist Artifacts e sempre podem ser acessadas pelo ID da execução no diretório artifacts/ no branch press-kit.

Arquitetura

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

Camadas

Camada	Linguagem	Função	Comunicação
Proxy MCP	JavaScript (Node.js)	Comunica-se com Claude via protocolo MCP, gerencia o ciclo de vida do daemon	stdio JSON-RPC
Daemon VNC	Swift/C (Apple Silicon)	Conexão VNC, captura de tela, injeção de entrada de mouse/teclado	stdin/stdout PC (NDJSON)

Protocolo PC (Chamada de Procedimento)

A comunicação entre o proxy e o daemon usa o protocolo PC sobre 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":{...}}

Escalonamento de Coordenadas

A resolução nativa do servidor VNC é reduzida para caber dentro de --max-dimension (padrão: 1280px). Claude trabalha de forma mais consistente com coordenadas escalonadas — o daemon lida com a conversão em segundo plano:

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

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

Estratégia de Tela

Claude minimiza o custo de tokens com uma abordagem de verificação progressiva:

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 usa o framework Apple Vision para OCR no dispositivo. Retorna conteúdo de texto com coordenadas de caixa delimitadora no espaço escalonado — permite cliques precisos sem consumir tokens de visão.

Instalação

Requisitos

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

Daemon

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

[!NOTE] claude-kvm-daemon é compilado e assinado digitalmente via CI (GitHub Actions). A saída da compilação é empacotada em dois formatos: um arquivo .tar.gz para distribuição via Homebrew e uma imagem de disco .dmg para notarização. O DMG é submetido aos servidores da Apple para notarização dentro do mesmo fluxo de trabalho — o processo pode ser acompanhado pelos logs de CI. O DMG notarizado está disponível como um Artefato de CI; o .tar.gz arquivado também é publicado como um release no repositório. A instalação via Homebrew acompanha este release.

Release · Código Fonte

Compilação LibVNC · Branch LibVNC

Homebrew Tap

Configuração MCP

Crie um arquivo .mcp.json no diretório do seu projeto:

{
  "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] A ferramenta é testada de ponta a ponta via CI — Claude executa tarefas sobre VNC enquanto um modelo de visão independente observa e verifica os resultados. Veja o Teste de Integração para execuções de fluxo de trabalho ao vivo, prompts de sistema e gravações de demonstração.

Configuração

Proxy MCP (ENV)

Parâmetro	Padrão	Descrição
`VNC_HOST`	`127.0.0.1`	Endereço do servidor VNC
`VNC_PORT`	`5900`	Número da porta VNC
`VNC_USERNAME`		Nome de usuário (obrigatório para ARD)
`VNC_PASSWORD`		Senha
`CLAUDE_KVM_DAEMON_PATH`	`claude-kvm-daemon`	Caminho do binário do daemon (não necessário se já estiver no PATH)
`CLAUDE_KVM_DAEMON_PARAMETERS`		Argumentos CLI adicionais para o daemon

Parâmetros do Daemon (CLI)

Argumentos adicionais passados para o daemon via CLAUDE_KVM_DAEMON_PARAMETERS:

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

Parâmetro	Padrão	Descrição
`--max-dimension`	`1280`	Dimensão máxima de escalonamento da tela (px)
`--connect-timeout`		Tempo limite de conexão VNC (segundos)
`--bits-per-sample`		Bits por amostra de pixel
`--no-reconnect`		Desabilitar reconexão automática
`-v, --verbose`		Log detalhado (stderr)

Configuração em Tempo de Execução (PC)

Todos os parâmetros de temporização e exibição são configuráveis em tempo de execução via método configure. Use get_timing para inspecionar os valores atuais.

Definir temporização:

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

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

Alterar escalonamento de exibição:

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

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

Redefinir para padrões:

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

Obter valores atuais:

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

Parâmetro	Padrão	Descrição
`max_dimension`	`1280`	Dimensão máxima da captura de tela
`cursor_crop_radius`	`150`	Raio de corte do cursor (px)
`click_hold_ms`	`50`	Duração da pressão do clique
`double_click_gap_ms`	`50`	Atraso entre cliques duplos
`hover_settle_ms`	`400`	Espera de estabilização ao pairar
`drag_position_ms`	`30`	Espera de posição pré-arrasto
`drag_press_ms`	`50`	Limiar de pressão para arrasto
`drag_step_ms`	`5`	Entre pontos de interpolação
`drag_settle_ms`	`30`	Estabilizar antes de soltar
`drag_pixels_per_step`	`20`	Densidade de pontos por pixel
`drag_min_steps`	`10`	Passos mínimos de interpolação
`scroll_press_ms`	`10`	Intervalo pressão-soltar da rolagem
`scroll_tick_ms`	`20`	Atraso entre ticks
`key_hold_ms`	`30`	Duração da pressão de tecla
`combo_mod_ms`	`10`	Atraso de estabilização do modificador
`type_key_ms`	`20`	Pressão de tecla durante digitação
`type_inter_key_ms`	`20`	Atraso entre caracteres
`type_shift_ms`	`10`	Estabilização da tecla Shift
`paste_settle_ms`	`30`	Espera pós-escrita na área de transferência

Ferramentas

Todas as operações são realizadas através de uma única ferramenta vnc_command:

Tela

Ação	Parâmetros	Descrição
`screenshot`		Captura de tela cheia em PNG
`cursor_crop`		Corte ao redor do cursor com sobreposição de mira
`diff_check`		Detectar mudanças na tela em relação à linha de base
`set_baseline`		Salvar tela atual como referência de diff

Mouse

Ação	Parâmetros	Descrição
`mouse_click`	`x, y, button?`	Clique (esquerdo\|direito\|meio)
`mouse_double_click`	`x, y`	Clique duplo
`mouse_move`	`x, y`	Mover cursor
`hover`	`x, y`	Mover + espera de estabilização
`nudge`	`dx, dy`	Movimento relativo do cursor
`mouse_drag`	`x, y, toX, toY`	Arrastar do início ao fim
`scroll`	`x, y, direction, amount?`	Rolar (cima\|baixo\|esquerda\|direita)

Teclado

Ação	Parâmetros	Descrição
`key_tap`	`key`	Pressionar tecla única (enter\|escape\|tab\|espaço\|...)
`key_combo`	`key` ou `keys`	Combinação de modificadores ("cmd+c" ou ["cmd","shift","3"])
`key_type`	`text`	Digitar texto caractere por caractere
`paste`	`text`	Colar texto via área de transferência

Detecção

Ação	Parâmetros	Descrição
`detect_elements`		Detecção de texto OCR com caixas delimitadoras (Apple Vision)

Retorna elementos de texto com coordenadas de caixa delimitadora no espaço escalonado:

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

Configuração

Ação	Parâmetros	Descrição
`configure`	`{<params>}`	Definir parâmetros de temporização/exibição em tempo de execução
`configure`	`{reset: true}`	Redefinir todos os parâmetros para os padrões
`get_timing`		Obter parâmetros atuais de temporização + exibição

Controle

Ação	Parâmetros	Descrição
`wait`	`ms?`	Aguardar (padrão 500ms)
`health`		Status da conexão + informações de exibição
`shutdown`		Desligamento gracioso do daemon

Autenticação

Métodos de autenticação VNC suportados:

VNC Auth — desafio-resposta baseado em senha (DES)
ARD — Apple Remote Desktop (Diffie-Hellman + AES-128-ECB)

O macOS é detectado automaticamente através da solicitação de credencial ARD do tipo de autenticação 30. Quando detectado, as teclas Meta são remapeadas para Super (compatibilidade com a tecla Command).

[!NOTE] Executando em um Mac bare-metal? Veja as Dicas de Preparação para Mac M1 para fortalecimento de VNC, tunelamento SSH e dicas de estabilidade de sessão.

"Claude" é uma marca registrada da Anthropic, PBC. Este projeto não é afiliado ou endossado pela Anthropic.