Native Devtools

native-devtools-mcp

Um servidor MCP para uso de computador em aplicativos nativos de desktop e mobile — macOS, Windows, Android e Chrome/Electron via CDP.

Adicione ao seu cliente com um clique:

Claude Code: claude mcp add native-devtools -- npx -y native-devtools-mcp

native-devtools-mcp dá a agentes de IA e clientes MCP controle direto sobre aplicativos nativos de desktop, navegadores Chrome/Electron e dispositivos Android — capturas de tela, OCR, busca de elementos com prioridade de acessibilidade, simulação de entrada, gerenciamento de janelas, Chrome DevTools Protocol (CDP) e ADB — tudo em um único servidor local. Funciona com Claude Desktop, Claude Code, Cursor e outros clientes compatíveis com MCP.

Início rápido

npx -y native-devtools-mcp

macOS	Windows

🚀 Recursos

• 👀 Visão Computacional: Capturas de tela de telas, janelas ou regiões com OCR integrado (Vision no macOS, Windows Media OCR no Windows).
• 🖱️ Simulação de Entrada: Clique, arraste, role, digite — direcionamento por coordenadas globais, relativas à janela e relativas à captura de tela.
• 🎯 Despacho AX com Precisão de Elemento (macOS): take_ax_snapshot → ax_click / ax_set_value / ax_select — despacho contra elementos da árvore de acessibilidade sem mover o mouse ou roubar o foco. O caminho preferido para aplicativos nativos do macOS.
• 🌐 Automação de Navegador (CDP): Chrome DevTools Protocol para Chrome e aplicativos Electron (Signal, Discord, VS Code, Slack) — clique, preenchimento, navegação e avaliação de JS no nível do DOM, sem um servidor Node.js separado.
• 📱 Android (ADB): Capturas de tela, busca de texto baseada em uiautomator, entrada e gerenciamento de aplicativos via USB ou Wi-Fi.
• 🧩 Correspondência de Modelos: load_image + find_image para ícones, alternadores e controles personalizados que o OCR não consegue identificar.
• 🪟 Gerenciamento de Janelas: Liste, foque, inicie e encerre aplicativos; grave janelas como quadros JPEG com carimbo de data/hora.
• 🔍 Rastreamento de Passagem do Mouse: Observe padrões de navegação do usuário com eventos de passagem do mouse filtrados por permanência — projetado para LLMs observando um usuário trabalhar.
• 🔒 Local e Privado: Execução 100% local. Capturas de tela e entrada nunca saem da sua máquina.

🧭 Três Abordagens para Interação

Escolha a abordagem que corresponde ao seu aplicativo alvo.

Para aplicativos nativos do macOS, o Despacho AX é o caminho preferido — é preciso em nível de elemento, não move o mouse e não rouba o foco. Veja a receita de Despacho AX para aplicativos nativos.

Há também um quarto caminho de nicho: AppDebugKit (app_connect / app_query / app_click) para aplicativos instrumentados com a biblioteca AppDebugKit. Útil principalmente para desenvolvedores testando seus próprios aplicativos.

🆚 Como se compara

Os concorrentes mais honestos são outros servidores MCP para uso de computador. Esta tabela compara native-devtools-mcp com os principais servidores MCP e duas bibliotecas não-MCP amplamente usadas.

Onde native-devtools-mcp se destaca: um único servidor MCP local cobrindo macOS + Windows + Chrome/Electron (CDP) + Android na mesma sessão, além do despacho AX do macOS com precisão de elemento que não move o cursor nem rouba o foco.

Limitações honestas:

• Sem Linux (contribuições bem-vindas — veja Linux Desktop MCP para uma alternativa baseada em AT-SPI2 enquanto isso)
• Automação de navegador é somente Chrome / Electron via CDP — sem Firefox, sem WebKit (para esses, use Playwright MCP)
• Somente com interface gráfica — depende de permissões de máquina real; não é uma grade de testes CI headless
• Sem iOS

Se você precisa apenas de automação web, Playwright MCP é mais maduro. Se você precisa apenas de mobile (iOS + Android + recursos profundos de dispositivo), Appium é mais maduro. Este servidor é para o caso transversal de desktop nativo + Chrome/Electron + Android.

📦 Instalação

As etapas de instalação são idênticas no macOS e no Windows.

Opção 1: Executar com npx (sem necessidade de instalação)

npx -y native-devtools-mcp

Opção 2: Instalação global

npm install -g native-devtools-mcp

Opção 3: Compilar a partir do código-fonte (Rust)

curl -fsSL https://raw.githubusercontent.com/vectora-foundry/native-devtools-mcp/master/scripts/build-from-source.sh | bash

git clone https://github.com/vectora-foundry/native-devtools-mcp
cd native-devtools-mcp
cargo build --release
# Binary: ./target/release/native-devtools-mcp

Configuração manual (sem o assistente de configuração)

{
  "mcpServers": {
    "native-devtools": {
      "command": "/Applications/NativeDevtools.app/Contents/MacOS/native-devtools-mcp"
    }
  }
}

{
  "mcpServers": {
    "native-devtools": {
      "command": "npx",
      "args": ["-y", "native-devtools-mcp"]
    }
  }
}

Permissões do macOS: o servidor precisa das permissões de Acessibilidade e Gravação de Tela. O assistente de configuração abre os painéis corretos de Ajustes do Sistema para você. Sem ambas, os cliques falham silenciosamente e as capturas de tela retornam um retângulo preto.

Linux ainda não é suportado. O servidor usa APIs específicas de plataforma (Core Graphics + Accessibility no macOS, Win32 + UI Automation no Windows) que não existem no Linux. Contribuições são bem-vindas — caminhos de captura de tela, entrada e AT-SPI para X11/Wayland seriam um bom primeiro problema.

🏁 Começando

Após a instalação, execute o assistente de configuração:

npx native-devtools-mcp setup

Isso irá:

1. Verificar permissões (macOS) — verifica Acessibilidade e Gravação de Tela, abre os Ajustes do Sistema se necessário.
2. Detectar seus clientes MCP — encontra Claude Desktop, Claude Code e Cursor.
3. Escrever a configuração — gera o JSON de configuração correto e oferece escrevê-lo para você.

Em seguida, reinicie seu cliente MCP e você estará pronto para usar.

Claude Desktop no macOS requer o pacote de aplicativo assinado (o Gatekeeper bloqueia o npx). Baixe NativeDevtools-X.X.X.dmg de GitHub Releases, arraste para /Applications e então execute a configuração — ele detectará o aplicativo e configurará o Claude Desktop para usá-lo.

VS Code, Windsurf e outros clientes: setup ainda não detecta esses automaticamente. Execute setup para as verificações de permissão e depois veja a configuração manual acima para o trecho de JSON de configuração.

Dica do Claude Code: Para evitar aprovar cada chamada de ferramenta (cliques, capturas de tela), adicione isto a .claude/settings.local.json:

{ "permissions": { "allow": ["mcp__native-devtools__*"] } }

⚠️ Segurança operacional

• Mãos longe: quando o agente estiver "dirigindo" (clicando / digitando), não mova o mouse nem digite. Conflitos de entrada de hardware real com entradas simuladas fazem os cliques caírem no lugar errado.
• O foco importa: garanta que a janela que você quer que o agente use esteja visível. Se um popup roubar o foco no meio do fluxo, o agente pode digitar na janela errada, a menos que verifique novamente primeiro.
• Prefira o Despacho AX no macOS quando quiser continuar usando a máquina — chamadas AX não movem o cursor e não roubam o foco da janela ativa.

📚 Receitas e Exemplos

• Índice de Receitas
• Configuração do Claude Desktop · Configuração do Claude Code · Configuração do Cursor
• Fluxo de Desktop de Ponta a Ponta
• Fluxo de Despacho AX para Aplicativos Nativos (macOS) — preferido para aplicativos nativos do macOS
• Fluxo de Clique em Aplicativos Nativos
• Fallback de OCR e Inspeção de Elementos
• Fluxo de Correspondência de Modelos
• Início Rápido no Android

🌐 Automação de Navegador (CDP)

Conecte-se a aplicativos Chrome ou Electron via Chrome DevTools Protocol para automação no nível do DOM — mais confiável que cliques baseados em coordenadas para conteúdo web.

# Launch Chrome with remote debugging
launch_app(app_name="Google Chrome", args=["--remote-debugging-port=9222", "--user-data-dir=/tmp/chrome-profile"])

# Connect and automate
cdp_connect(port=9222)
cdp_navigate(url="https://example.com")
cdp_find_elements(query="search")    # DOM walker with element UIDs (d1, d2, ...)
cdp_fill(uid="d1", value="search query")
cdp_press_key(key="Enter")
cdp_wait_for(text=["Results"])

21 ferramentas CDP — resumo da página, snapshot do DOM, encontrar elementos, contexto do elemento, clique, passagem do mouse, preenchimento, digitação, pressionar tecla, navegação, lidar com diálogos, gerenciar abas, aguardar texto ou mudanças na página, avaliar JS, inspeção de elementos e mais. Todas as ferramentas CDP estão sempre listadas; elas retornam um erro "Sem conexão CDP" até que cdp_connect tenha sucesso. Funciona com Chrome 136+, Chromium e aplicativos Electron (Signal, Discord, VS Code, Slack). Veja AGENTS.md para a referência completa das ferramentas.

Nota do Chrome 136+: requer --user-data-dir=<path> junto com --remote-debugging-port — o Chrome ignora silenciosamente a porta de depuração com o perfil padrão. Aplicativos Electron só precisam de --remote-debugging-port.

📱 Suporte ao Android

O suporte ao Android é integrado. O servidor se comunica com dispositivos Android via ADB (USB ou Wi-Fi), fornecendo capturas de tela, simulação de entrada, busca de elementos de interface e gerenciamento de aplicativos.

Pré-requisitos

1. ADB instalado no host (brew install android-platform-tools no macOS, ou via Android SDK).
2. Depuração USB habilitada no dispositivo (Configurações > Opções do desenvolvedor > Depuração USB).
3. Servidor ADB em execução — inicia automaticamente quando você executa adb devices.

Ferramentas

Todas as ferramentas do Android são prefixadas com android_. android_list_devices e android_connect estão sempre disponíveis; as demais aparecem dinamicamente após conectar a um dispositivo:

Fluxo de trabalho típico

android_list_devices           → find your device serial
android_connect(serial="...")  → connect (unlocks android_* tools)
android_screenshot             → see what's on screen
android_find_text(text="OK")   → locate a button
android_click(x=..., y=...)    → tap it

adb tcpip 5555
adb connect <phone-ip>:5555

cargo test --test android_smoke_tests -- --ignored --test-threads=1

🔐 Segurança e Confiança

Esta ferramenta exige permissões de Acessibilidade e Gravação de Tela — isso é muita confiança. Veja como verificar se ela merece.

Verifique seu binário

native-devtools-mcp verify

Calcula o hash SHA-256 do binário em execução e o compara com as somas de verificação oficiais publicadas na página GitHub Releases. Se o hash corresponder, você está executando uma compilação oficial não modificada.

Audite o código

SECURITY_AUDIT.md documenta exatamente quais permissões são usadas, onde no código-fonte, e inclui um prompt de auditoria de LLM que você pode colar em qualquer modelo de IA para uma revisão de segurança independente.

O que este servidor NÃO faz

• Sem acesso de rede não solicitado. O servidor nunca faz contato com o servidor. A rede só é usada quando o cliente MCP invoca explicitamente app_connect (WebSocket para um servidor de depuração local) ou quando você executa o subcomando verify (busca somas de verificação do GitHub).
• Sem varredura de arquivos. Não lê nem indexa seus arquivos. As únicas leituras de arquivos são load_image (um caminho que o cliente MCP fornece explicitamente) e arquivos temporários de curta duração para capturas de tela (excluídos imediatamente após a captura).
• Sem persistência em segundo plano. Sai quando o cliente MCP desconecta.
• Sem exfiltração de dados. As capturas de tela são retornadas ao cliente MCP via stdout, nunca armazenadas ou transmitidas para outro lugar.

❓ FAQ

Funciona no Linux? Ainda não — apenas macOS, Windows e Android. O servidor usa Core Graphics + APIs de Acessibilidade no macOS e Win32 + UI Automation no Windows. Uma porta X11/Wayland + AT-SPI seria uma contribuição bem-vinda.

Precisa de uma chave de API? Não. O servidor roda inteiramente localmente e não faz chamadas de API de saída. Seu cliente MCP pode precisar de sua própria chave de API de LLM (Anthropic, OpenAI, etc.), mas o servidor em si não.

Qual é a diferença em relação ao Claude Computer Use? Claude Computer Use é uma ferramenta beta da API Anthropic — funciona com Claude Opus, Sonnet e Haiku atrás de um cabeçalho beta e requer uma chave de API Anthropic. Opera via capturas de tela + ações de mouse/teclado baseadas em coordenadas. native-devtools-mcp é agnóstico de modelo (qualquer coisa que fale MCP), roda 100% localmente sem dependência de API, e adiciona despacho AX preciso de elementos no macOS, Chrome DevTools Protocol e Android via ADB.

Funciona com modelos locais (Ollama, LM Studio, etc.)? Sim — desde que o cliente fale MCP. Qualquer cliente compatível com MCP pode conectar. Clientes não-MCP podem envolver o servidor atrás de uma ponte.

É gratuito / código aberto? Sim, licenciado sob MIT. Veja LICENSE.

Ele grava o que estou fazendo? Não — a menos que você chame explicitamente start_recording, que grava em um diretório que você especifica e para em stop_recording. O rastreamento de foco também só é executado enquanto start_hover_tracking está ativo. Nada é gravado ou enviado para qualquer lugar caso contrário.

Como ele se compara ao Playwright ou Playwright MCP? Playwright é a escolha madura para automação web pura — Chromium, Firefox e WebKit, além de suporte de primeira classe para Electron via _electron.launch() e automação Android experimental. Playwright MCP o envolve como um servidor MCP para agentes de IA. Se você só precisa de automação web / Electron, use Playwright MCP. native-devtools-mcp cobre aplicativos nativos macOS / Windows e dispositivos Android além de Chrome/Electron, em um único servidor MCP local — o que Playwright MCP não faz.

🏗️ Arquitetura

graph TD
    Client[Claude / LLM Client] <-->|JSON-RPC 2.0| Server[native-devtools-mcp]
    Server -->|Direct API| Sys[System APIs]
    Server -->|CDP / WebSocket| Chrome[Chrome / Electron]
    Server -->|WebSocket| Debug[AppDebugKit]
    Server -->|ADB Protocol| Android[Android Device]

    subgraph "Your Machine"
        Sys -->|Screen/OCR| macOS[CoreGraphics / Vision]
        Sys -->|Input| Win[Win32 / SendInput]
        Sys -->|Text Search| UIA[UI Automation]
        Sys -->|AX Snapshot + Dispatch| AXapi[Accessibility API - macOS]
        Chrome -.->|DOM-level| ChromeApp[Web Page / Electron UI]
        Debug -.->|Inspect| App[Instrumented App]
    end

    subgraph "Android Device (USB/Wi-Fi)"
        Android -->|screencap| Screen[Screenshots]
        Android -->|input| Input[Tap / Swipe / Type]
        Android -->|uiautomator| UITree[UI Hierarchy]
    end

screen_x = screenshot_origin_x + (pixel_x / screenshot_scale)
screen_y = screenshot_origin_y + (pixel_y / screenshot_scale)

🪟 Notas sobre Windows

Funciona imediatamente no Windows 10/11.

• Usa APIs Win32 padrão (GDI, SendInput).
• find_text usa UI Automation (UIA) como mecanismo de busca principal, consultando a árvore de acessibilidade para nomes de elementos. Esta é a mesma abordagem de acessibilidade em primeiro lugar usada no macOS. Faz fallback para OCR automaticamente quando UIA não encontra correspondências.
• OCR usa o mecanismo OCR do Windows Media integrado (offline).
• Não pode interagir com janelas "Executar como Administrador" a menos que o próprio servidor MCP também esteja rodando como Administrador.
• Gravação de tela usa GDI/BitBlt em fps configurável (padrão 5). Para fps mais altos ou captura de jogos, a API DXGI Desktop Duplication forneceria captura acelerada por hardware — uma atualização futura planejada.

🤖 Para Agentes de IA

Uso orientado a agentes — definições de intenção, exemplos de esquema, padrões de raciocínio — está em AGENTS.md. É uma referência compacta e otimizada para tokens, projetada para ingestão por LLMs (Claude, Gemini, GPT, modelos locais). Se você é um agente de IA lendo este README para decidir se deve usar o servidor, vá para lá em seguida.

⭐ Histórico de Estrelas

📜 Licença

MIT © sh3ll3x3c