Native Devtools

native-devtools-mcp

Un servidor MCP para uso informático en aplicaciones nativas de escritorio y móviles: macOS, Windows, Android y Chrome/Electron vía CDP.

Añade a tu cliente con un clic:

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

native-devtools-mcp da a los agentes de IA y clientes MCP control directo sobre aplicaciones nativas de escritorio, navegadores Chrome/Electron y dispositivos Android: capturas de pantalla, OCR, búsqueda de elementos con accesibilidad como prioridad, simulación de entrada, gestión de ventanas, Protocolo de DevTools de Chrome (CDP) y ADB, todo en un único servidor local. Funciona con Claude Desktop, Claude Code, Cursor y otros clientes compatibles con MCP.

Inicio rápido

npx -y native-devtools-mcp

macOS	Windows

🚀 Características

• 👀 Visión por computadora: capturas de pantalla, ventanas o regiones con OCR integrado (Vision en macOS, Windows Media OCR en Windows).
• 🖱️ Simulación de entrada: clic, arrastrar, desplazar, escribir: coordenadas globales, relativas a la ventana y relativas a la captura de pantalla.
• 🎯 Despacho AX de precisión por elemento (macOS): take_ax_snapshot → ax_click / ax_set_value / ax_select: despacho contra elementos del árbol de Accesibilidad sin mover el ratón ni robar el foco. La vía preferida para aplicaciones nativas de macOS.
• 🌐 Automatización de navegadores (CDP): Protocolo de DevTools de Chrome para aplicaciones Chrome y Electron (Signal, Discord, VS Code, Slack): clic, relleno, navegación y evaluación de JS a nivel de DOM sin un servidor Node.js separado.
• 📱 Android (ADB): capturas de pantalla, búsqueda de texto basada en uiautomator, entrada y gestión de aplicaciones por USB o Wi-Fi.
• 🧩 Coincidencia de plantillas: load_image + find_image para iconos, conmutadores y controles personalizados que el OCR no puede identificar.
• 🪟 Gestión de ventanas: listar, enfocar, lanzar y cerrar aplicaciones; grabar ventanas como fotogramas JPEG con marca de tiempo.
• 🔍 Seguimiento de cursor: observa los patrones de navegación del usuario con eventos de desplazamiento filtrados por permanencia: diseñado para que los LLM observen al usuario trabajar.
• 🔒 Local y privado: ejecución 100 % local. Las capturas de pantalla y la entrada nunca salen de tu máquina.

🧭 Tres enfoques de interacción

Elige el enfoque que coincida con tu aplicación objetivo.

Para aplicaciones nativas de macOS, el Despacho AX es la vía preferida: es preciso por elemento, no mueve el ratón y no roba el foco. Consulta la receta de Despacho AX para aplicaciones nativas.

También existe una cuarta vía especializada: AppDebugKit (app_connect / app_query / app_click) para aplicaciones instrumentadas con la biblioteca AppDebugKit. Resulta útil sobre todo para desarrolladores que prueban sus propias aplicaciones.

🆚 Comparación

Los rivales más honestos son otros servidores MCP para uso informático. Esta tabla compara native-devtools-mcp con los servidores MCP líderes y dos bibliotecas no MCP muy utilizadas.

Donde native-devtools-mcp destaca: un único servidor MCP local que cubre macOS + Windows + Chrome/Electron (CDP) + Android en la misma sesión, además del despacho AX de precisión por elemento en macOS que no mueve el cursor ni roba el foco.

Límites honestos:

• Sin Linux (las contribuciones son bienvenidas; consulta Linux Desktop MCP para una alternativa basada en AT-SPI2 mientras tanto)
• La automatización de navegadores es solo para Chrome / Electron vía CDP: sin Firefox, sin WebKit (para esos, usa Playwright MCP)
• Solo con pantalla — depende de permisos de máquina real; no es una cuadrícula de pruebas CI sin interfaz
• Sin iOS

Si necesitas solo automatización web, Playwright MCP es más maduro. Si necesitas solo móvil (iOS + Android + funciones avanzadas de dispositivo), Appium es más maduro. Este servidor es para el caso transversal de escritorio nativo + Chrome/Electron + Android.

📦 Instalación

Los pasos de instalación son idénticos en macOS y Windows.

Opción 1: Ejecutar con npx (sin necesidad de instalar)

npx -y native-devtools-mcp

Opción 2: Instalación global

npm install -g native-devtools-mcp

Opción 3: Compilar desde el código fuente (Rust)

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

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

Configuración manual (sin el asistente de configuración)

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

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

Permisos de macOS: el servidor necesita permisos de Accesibilidad y Grabación de pantalla. El asistente de configuración abre los paneles correctos de Ajustes del Sistema por ti. Sin ambos, los clics fallan silenciosamente y las capturas de pantalla devuelven un rectángulo negro.

Linux aún no es compatible. El servidor usa API específicas de plataforma (Core Graphics + Accesibilidad en macOS, Win32 + Automatización de UI en Windows) que no existen en Linux. Las contribuciones son bienvenidas: las rutas X11/Wayland de captura, entrada y AT-SPI serían un buen primer issue.

🏁 Primeros pasos

Tras instalar, ejecuta el asistente de configuración:

npx native-devtools-mcp setup

Esto hará lo siguiente:

1. Comprobar permisos (macOS): verifica Accesibilidad y Grabación de pantalla, abre Ajustes del Sistema si es necesario.
2. Detectar tus clientes MCP: encuentra Claude Desktop, Claude Code y Cursor.
3. Escribir la configuración: genera el JSON de configuración correcto y ofrece escribirlo por ti.

Luego reinicia tu cliente MCP y listo.

Claude Desktop en macOS requiere el paquete de aplicación firmado (Gatekeeper bloquea npx). Descarga NativeDevtools-X.X.X.dmg desde GitHub Releases, arrástralo a /Applications y luego ejecuta la configuración: detectará la aplicación y configurará Claude Desktop para usarla.

VS Code, Windsurf y otros clientes: setup aún no los detecta automáticamente. Ejecuta setup para las comprobaciones de permisos y luego consulta la configuración manual de arriba para el fragmento JSON.

Consejo para Claude Code: para evitar aprobar cada llamada de herramienta (clics, capturas), añade esto a .claude/settings.local.json:

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

⚠️ Seguridad operativa

• Manos fuera: cuando el agente está "conduciendo" (haciendo clic / escribiendo), no muevas tu ratón ni escribas. Las entradas de hardware reales entran en conflicto con las simuladas y los clics caen en el lugar equivocado.
• El foco importa: asegúrate de que la ventana que quieres que use el agente esté visible. Si una ventana emergente roba el foco a mitad del flujo, el agente podría escribir en la ventana equivocada a menos que vuelva a comprobarlo antes.
• Prefiere el Despacho AX en macOS cuando quieras seguir usando la máquina: las llamadas AX no mueven el cursor ni roban el foco de la ventana activa.

📚 Recetas y ejemplos

• Índice de recetas
• Configuración de Claude Desktop · Configuración de Claude Code · Configuración de Cursor
• Flujo de escritorio de extremo a extremo
• Flujo de Despacho AX para aplicaciones nativas (macOS) — preferido para aplicaciones nativas de macOS
• Flujo de clic en aplicaciones nativas
• Respaldo por OCR e inspección de elementos
• Flujo de coincidencia de plantillas
• Inicio rápido de Android

🌐 Automatización de navegadores (CDP)

Conéctate a aplicaciones Chrome o Electron mediante el Protocolo de DevTools de Chrome para automatización a nivel de DOM: más fiable que el clic basado en coordenadas para contenido 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"])

18 herramientas CDP — instantánea del DOM, buscar elementos, clic, pasar el cursor, rellenar, escribir, pulsar tecla, navegar, gestionar diálogos, administrar pestañas, evaluar JS, inspección de elementos y más. Funciona con Chrome 136+, Chromium y aplicaciones Electron (Signal, Discord, VS Code, Slack). Consulta AGENTS.md para la referencia completa de herramientas.

Nota para Chrome 136+: requiere --user-data-dir=<path> además de --remote-debugging-port: Chrome ignora silenciosamente el puerto de depuración con el perfil predeterminado. Las aplicaciones Electron solo necesitan --remote-debugging-port.

📱 Soporte de Android

El soporte de Android está integrado. El servidor se comunica con los dispositivos Android a través de ADB (USB o Wi-Fi) y proporciona capturas de pantalla, simulación de entrada, búsqueda de elementos de UI y gestión de aplicaciones.

Requisitos previos

1. ADB instalado en el host (brew install android-platform-tools en macOS, o mediante Android SDK).
2. Depuración USB habilitada en el dispositivo (Ajustes > Opciones de desarrollador > Depuración USB).
3. Servidor ADB en ejecución: se inicia automáticamente cuando ejecutas adb devices.

Herramientas

Todas las herramientas de Android llevan el prefijo android_ y aparecen dinámicamente tras conectarse a un dispositivo:

Flujo de trabajo 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

🔐 Seguridad y confianza

Esta herramienta requiere permisos de Accesibilidad y Grabación de pantalla — eso es mucha confianza. Así puedes verificar que la merece.

Verifica tu binario

native-devtools-mcp verify

Calcula el hash SHA-256 del binario en ejecución y lo compara con las sumas de verificación oficiales publicadas en la página de GitHub Releases. Si el hash coincide, estás ejecutando una compilación oficial sin modificaciones.

Audita el código

SECURITY_AUDIT.md documenta exactamente qué permisos se usan, dónde en el código fuente, e incluye un prompt de auditoría LLM que puedes pegar en cualquier modelo de IA para una revisión de seguridad independiente.

Lo que este servidor NO hace

• Sin acceso de red no solicitado. El servidor nunca se comunica con el exterior. La red solo se usa cuando el cliente MCP invoca explícitamente app_connect (WebSocket a un servidor de depuración local) o cuando ejecutas el subcomando verify (obtiene sumas de verificación de GitHub).
• Sin escaneo de archivos. No lee ni indexa tus archivos. Las únicas lecturas de archivos son load_image (una ruta que el cliente MCP proporciona explícitamente) y archivos temporales de corta duración para capturas de pantalla (eliminados inmediatamente después de la captura).
• Sin persistencia en segundo plano. Se cierra cuando el cliente MCP se desconecta.
• Sin exfiltración de datos. Las capturas de pantalla se devuelven al cliente MCP a través de stdout, nunca se almacenan ni transmiten a otro lugar.

❓ FAQ

¿Funciona en Linux? Aún no — solo macOS, Windows y Android. El servidor usa Core Graphics + APIs de Accesibilidad en macOS y Win32 + UI Automation en Windows. Un port a X11/Wayland + AT-SPI sería una contribución bienvenida.

¿Necesita una clave API? No. El servidor se ejecuta completamente en local y no realiza llamadas API salientes. Tu cliente MCP puede necesitar su propia clave API de LLM (Anthropic, OpenAI, etc.), pero el servidor en sí no.

¿En qué se diferencia de Claude Computer Use? Claude Computer Use es una herramienta beta de la API de Anthropic — funciona con Claude Opus, Sonnet y Haiku detrás de un encabezado beta y requiere una clave API de Anthropic. Opera mediante capturas de pantalla + acciones de ratón/teclado basadas en coordenadas. native-devtools-mcp es agnóstico al modelo (cualquier cosa que hable MCP), se ejecuta 100% en local sin dependencia de API, y añade despacho AX de macOS con precisión de elementos, Chrome DevTools Protocol y Android sobre ADB.

¿Funciona con modelos locales (Ollama, LM Studio, etc.)? Sí — siempre que el cliente hable MCP. Cualquier cliente compatible con MCP puede conectarse. Los clientes que no son MCP pueden envolver el servidor detrás de un puente.

¿Es gratuito / de código abierto? Sí, con licencia MIT. Consulta LICENSE.

¿Graba lo que hago? No — a menos que llames explícitamente a start_recording, que escribe en un directorio que especifiques y se detiene en stop_recording. El seguimiento de hover también se ejecuta solo mientras start_hover_tracking está activo. Nada se graba ni se envía a ningún lugar de otro modo.

¿Cómo se compara con Playwright o Playwright MCP? Playwright es la opción madura para automatización web pura — Chromium, Firefox y WebKit, además de soporte de primera clase para Electron mediante _electron.launch() y automatización experimental de Android. Playwright MCP lo envuelve como un servidor MCP para agentes de IA. Si solo necesitas automatización web / Electron, usa Playwright MCP. native-devtools-mcp cubre aplicaciones nativas de macOS / Windows y dispositivos Android además de Chrome/Electron, en un único servidor MCP local — algo que Playwright MCP no hace.

🏗️ Arquitectura

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 de Windows

Funciona sin configuración adicional en Windows 10/11.

• Usa APIs Win32 estándar (GDI, SendInput).
• find_text usa UI Automation (UIA) como mecanismo de búsqueda principal, consultando el árbol de accesibilidad para nombres de elementos. Este es el mismo enfoque de accesibilidad primero usado en macOS. Recurre automáticamente a OCR cuando UIA no encuentra coincidencias.
• El OCR usa el motor OCR de Windows Media integrado (sin conexión).
• No puede interactuar con ventanas de "Ejecutar como administrador" a menos que el propio servidor MCP también se ejecute como administrador.
• La grabación de pantalla usa GDI/BitBlt a fps configurables (5 por defecto). Para fps más altos o captura de juegos, la API DXGI Desktop Duplication proporcionaría captura acelerada por hardware — una mejora futura planificada.

🤖 Para agentes de IA

Uso orientado a agentes — definiciones de intención, ejemplos de esquemas, patrones de razonamiento — vive en AGENTS.md. Es una referencia compacta y optimizada para tokens diseñada para ser ingerida por LLMs (Claude, Gemini, GPT, modelos locales). Si eres un agente de IA leyendo este README para decidir si usar el servidor, ve allí a continuación.

⭐ Historial de estrellas

📜 Licencia

MIT © sh3ll3x3c