mobile-device-mcp

mobile-device-mcp

Servidor MCP que brinda a los asistentes de codificación con IA (Claude Code, Cursor, Windsurf) la capacidad de ver e interactuar con dispositivos móviles. 49 herramientas para capturas de pantalla, inspección de UI, interacción táctil, análisis visual impulsado por IA, inspección del árbol de widgets de Flutter, grabación de video y generación de pruebas.

Los asistentes de IA pueden leer tu código pero no pueden ver tu teléfono. Esto lo soluciona.

¿Por qué este?

El problema

Los desarrolladores web tienen DevTools del navegador, Playwright y Puppeteer: los asistentes de IA pueden hacer clic, tomar capturas de pantalla y verificar correcciones. ¿Desarrolladores móviles? Están atascados tomando capturas de pantalla manualmente, copiando registros y describiendo lo que hay en pantalla. Son middleware humano entre la IA y el dispositivo.

Qué hace esto

Developer: "The login button doesn't work"

Without this tool:                    With this tool:
  1. Manually screenshot              1. AI calls take_screenshot -> sees the screen
  2. Paste into AI chat               2. AI calls smart_tap("login button") -> taps it
  3. AI guesses what's wrong          3. AI calls verify_screen("error message shown") -> sees result
  4. Apply fix, rebuild               4. AI calls visual_diff -> confirms fix worked
  5. Repeat 4-5 times                 5. Done.

Inicio rápido

Instalación

npx mobile-device-mcp

No se necesita instalación global. Se ejecuta directamente mediante npx.

Requisitos previos

• Node.js 18+
• Dispositivo/emulador Android conectado mediante ADB
• ADB instalado (Android SDK Platform Tools)

Configuración (una vez, 30 segundos)

1. Obtén una clave de Google AI (nivel gratuito disponible): aistudio.google.com/apikey

2. Agrega .mcp.json a la raíz de tu proyecto:

macOS / Linux:

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key"
      }
    }
  }
}

Con clave de licencia Pro (después de comprar Pro):

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "MOBILE_MCP_LICENSE_KEY": "MDMCP-XXXXX-XXXXX-XXXXX-XXXXX"
      }
    }
  }
}

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "MOBILE_MCP_LICENSE_KEY": "MDMCP-XXXXX-XXXXX-XXXXX-XXXXX"
      }
    }
  }
}

3. Abre tu asistente de codificación con IA desde ese directorio. Eso es todo.

El servidor se inicia y se detiene automáticamente: nunca lo ejecutas manualmente. Tu asistente de IA lo gestiona como un proceso en segundo plano mediante el protocolo MCP.

Verifica que funciona

Claude Code: escribe /mcp -- deberías ver mobile-device: Connected

Cursor: revisa el panel de MCP en la configuración

Luego simplemente habla con tu teléfono:

You: "Open my app, tap the login button, type test@email.com in the email field"
AI:  [takes screenshot -> sees the screen -> smart_tap("login button") -> smart_type("email field", "test@email.com")]

You: "Find all the bugs on this screen"
AI:  [analyze_screen -> inspects layout, checks for overflow, missing labels, broken states]

You: "Navigate to settings and verify dark mode works"
AI:  [smart_tap("settings") -> take_screenshot -> smart_tap("dark mode toggle") -> visual_diff -> reports result]

Sin scripts de prueba. Sin capturas de pantalla manuales. Solo describe lo que quieres en lenguaje natural.

Funciona con cualquier asistente de codificación con IA

Todos usan la misma configuración JSON: solo colócala en el archivo correcto para tu editor.

Úsalo en cualquier proyecto

Copia .mcp.json en cualquier proyecto móvil (Flutter, React Native, Kotlin, Swift) y tu asistente de IA obtiene superpoderes de dispositivo en ese directorio. No se necesita instalación global.

Gratis vs Pro

Gratis (14 herramientas) -- no se necesita clave de licencia

Pro (35 herramientas adicionales) -- ₹499/mes

Obtén la licencia Pro -- desbloquea las 49 herramientas. Después del pago, recibirás tu clave de licencia por correo electrónico en 1 hora. Agrégala a tu .mcp.json:

{
  "mcpServers": {
    "mobile-device": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mobile-device-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "MOBILE_MCP_LICENSE_KEY": "your-license-key"
      }
    }
  }
}

Análisis visual con IA (12 herramientas)

Usa la visión de IA (Claude o Gemini) para entender lo que hay en pantalla.

Árbol de widgets de Flutter (10 herramientas)

Conéctate a aplicaciones Flutter en ejecución mediante el Protocolo de Servicio de Dart VM. Mapea cada widget a su ubicación en el código fuente (file:line).

Simulador iOS (4 herramientas)

Solo macOS. Controla simuladores iOS mediante xcrun simctl.

Grabación de video (2 herramientas)

Generación de pruebas (3 herramientas)

Gestión de aplicaciones (4 herramientas)

Rendimiento

El servidor está optimizado para minimizar la latencia y los costos de tokens de IA:

• Búsqueda de elementos en 4 niveles: aplicación complementaria (instantánea) -> coincidencia de texto local (<1ms) -> IA en caché -> IA nueva. smart_tap es 35 veces más rápida que las llamadas de IA ingenuas (205 ms vs 7,6 s).
• Aplicación complementaria: la aplicación Android basada en AccessibilityService proporciona el árbol de UI en 105 ms (23 veces más rápido que los 2448 ms de UIAutomator). Se instala automáticamente en el primer uso.
• Compresión de capturas de pantalla: las herramientas de IA comprimen automáticamente a JPEG q=60, 400w -- 89% más pequeñas (251KB -> 28KB) sin pérdida de calidad de IA.
• Captura en paralelo: captura de pantalla + árbol de UI obtenidos simultáneamente mediante Promise.all().
• Caché TTL: caché de 5 segundos evita llamadas ADB redundantes para el uso rápido de herramientas.

Variables de entorno

Arquitectura

src/
|-- index.ts              # CLI entry point (auto-discovery, env config)
|-- server.ts             # MCP server factory
|-- license.ts            # License validation and tier gating
|-- types.ts              # Shared interfaces
|-- drivers/android/      # ADB driver (DeviceDriver implementation)
|   |-- adb.ts            # Low-level ADB command wrapper
|   |-- companion-client.ts # TCP client for companion app
|   +-- index.ts          # AndroidDriver class (4-strategy UI element retrieval)
|-- drivers/flutter/      # Dart VM Service driver
|   |-- index.ts          # FlutterDriver (discovery, inspection, source mapping, hot reload)
|   +-- vm-service.ts     # JSON-RPC 2.0 WebSocket client (DDS redirect handling)
|-- drivers/ios/          # iOS Simulator driver (macOS only)
|   |-- index.ts          # IOSSimulatorDriver via xcrun simctl
|   +-- simctl.ts         # Low-level simctl command wrapper
|-- tools/                # MCP tool registrations (free + pro gating)
|   |-- device-tools.ts   # Device management
|   |-- screen-tools.ts   # Screenshots & UI inspection
|   |-- interaction-tools.ts # Touch, type, keys
|   |-- app-tools.ts      # App management
|   |-- log-tools.ts      # Logcat
|   |-- ai-tools.ts       # AI-powered tools
|   |-- flutter-tools.ts  # Flutter widget inspection
|   |-- ios-tools.ts      # iOS simulator tools
|   |-- video-tools.ts    # Screen recording
|   +-- recording-tools.ts # Test generation
|-- recording/            # Test script generation
|   |-- recorder.ts       # ActionRecorder (records MCP tool calls)
|   +-- generator.ts      # TestGenerator (TypeScript/Python/JSON output)
|-- ai/                   # AI visual analysis engine
|   |-- client.ts         # Multi-provider client (Anthropic + Google)
|   |-- prompts.ts        # System prompts & UI element summarizer
|   |-- analyzer.ts       # ScreenAnalyzer orchestrator (caching, parallel capture)
|   +-- element-search.ts # Local element search (text/alias matching, no AI needed)
+-- utils/
    |-- discovery.ts      # ADB auto-discovery
    +-- image.ts          # PNG parsing, JPEG compression, bilinear resize

companion-app/            # Android companion app (Kotlin)
                          # AccessibilityService + TCP JSON-RPC for fast UI tree

Hoja de ruta

• Soporte para dispositivos iOS físicos
• Orquestación de múltiples dispositivos
• Integración CI/CD
• Soporte para granjas de dispositivos en la nube

Probado en

• Dispositivos: Pixel 8 (Android 16), serie Samsung Galaxy, emuladores Android
• Aplicaciones: Telegram, Instagram, Spotify, WhatsApp, YouTube, Chrome, Configuración y aplicaciones Flutter
• Proveedores de IA: Google Gemini 2.5 Flash, Anthropic Claude
• Plataformas: Windows 11, macOS (simuladores iOS)
• Conexión: ADB por USB e inalámbrico

Licencia

Business Source License 1.1

• Gratis para uso individual y no comercial
• El uso comercial requiere una licencia de pago
• Se convierte a Apache 2.0 el 23 de marzo de 2030

Consulta LICENSE para conocer los términos completos.