mobile-device-mcp

mobile-device-mcp

Servidor MCP que dá aos assistentes de codificação com IA (Claude Code, Cursor, Windsurf) a capacidade de ver e interagir com dispositivos móveis. 49 ferramentas para capturas de tela, inspeção de UI, interação por toque, análise visual com IA, inspeção da árvore de widgets Flutter, gravação de vídeo e geração de testes.

Assistentes de IA podem ler seu código, mas não conseguem ver seu celular. Isso resolve esse problema.

Por Que Este?

O Problema

Desenvolvedores web têm DevTools de navegador, Playwright e Puppeteer — assistentes de IA podem clicar, tirar capturas de tela e verificar correções. Desenvolvedores mobile? Eles ficam presos tirando capturas de tela manualmente, copiando logs e descrevendo o que está na tela. Eles são middleware humano entre a IA e o dispositivo.

O Que Isso Faz

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.

Início Rápido

Instalação

npx mobile-device-mcp

Não é necessária instalação global. Executa diretamente via npx.

Pré-requisitos

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

Configuração (única vez, 30 segundos)

1. Obtenha uma chave do Google AI (nível gratuito disponível): aistudio.google.com/apikey

2. Adicione .mcp.json à raiz do seu projeto:

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

Com chave de licença Pro (após comprar o 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. Abra seu assistente de codificação com IA a partir desse diretório. É isso.

O servidor inicia e para automaticamente — você nunca o executa manualmente. Seu assistente de IA o gerencia como um processo em segundo plano via protocolo MCP.

Verifique se Funciona

Claude Code: digite /mcp — você deve ver mobile-device: Connected

Cursor: verifique o painel MCP nas configurações

Depois é só conversar com seu celular:

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]

Sem scripts de teste. Sem capturas de tela manuais. Apenas descreva o que você quer em linguagem simples.

Funciona com Qualquer Assistente de Codificação com IA

Todos usam a mesma configuração JSON — basta colocá-la no arquivo correto para seu editor.

Adicione a Qualquer Projeto

Copie .mcp.json para qualquer projeto mobile — Flutter, React Native, Kotlin, Swift — e seu assistente de IA ganha superpoderes de dispositivo nesse diretório. Não é necessária instalação global.

Grátis vs Pro

Grátis (14 ferramentas) — sem necessidade de chave de licença

Pro (35 ferramentas adicionais) — ₹499/mês

Obter Licença Pro — desbloqueie todas as 49 ferramentas. Após o pagamento, você receberá sua chave de licença por e-mail em até 1 hora. Adicione-a ao seu .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álise Visual com IA (12 ferramentas)

Use visão de IA (Claude ou Gemini) para entender o que está na tela.

Árvore de Widgets Flutter (10 ferramentas)

Conecta-se a aplicativos Flutter em execução via Dart VM Service Protocol. Mapeia cada widget para sua localização no código-fonte (file:line).

Simulador iOS (4 ferramentas)

Somente macOS. Controla simuladores iOS via xcrun simctl.

Gravação de Vídeo (2 ferramentas)

Geração de Testes (3 ferramentas)

Gerenciamento de Aplicativos (4 ferramentas)

Desempenho

O servidor é otimizado para minimizar latência e custos de tokens de IA:

• Busca de elementos em 4 níveis: aplicativo complementar (instantâneo) -> correspondência de texto local (<1ms) -> IA em cache -> IA nova. smart_tap é 35x mais rápido que chamadas de IA ingênuas (205ms vs 7,6s).
• Aplicativo complementar: aplicativo Android baseado em AccessibilityService fornece árvore de UI em 105ms (23x mais rápido que os 2448ms do UIAutomator). Instala automaticamente no primeiro uso.
• Compressão de captura de tela: ferramentas de IA comprimem automaticamente para JPEG q=60, 400w — 89% menor (251KB -> 28KB) sem perda de qualidade para IA.
• Captura paralela: captura de tela + árvore de UI obtidas simultaneamente via Promise.all().
• Cache TTL: cache de 5 segundos evita chamadas ADB redundantes para uso rápido de ferramentas.

Variáveis de Ambiente

Arquitetura

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

Roadmap

• Suporte a dispositivo físico iOS
• Orquestração multi-dispositivo
• Integração CI/CD
• Suporte a fazenda de dispositivos em nuvem

Testado Em

• Dispositivos: Pixel 8 (Android 16), série Samsung Galaxy, emuladores Android
• Aplicativos: Telegram, Instagram, Spotify, WhatsApp, YouTube, Chrome, Configurações e aplicativos Flutter
• Provedores de IA: Google Gemini 2.5 Flash, Anthropic Claude
• Plataformas: Windows 11, macOS (simuladores iOS)
• Conexão: ADB via USB e sem fio

Licença

Business Source License 1.1

• Grátis para indivíduos e uso não comercial
• Uso comercial requer licença paga
• Converte para Apache 2.0 em 23 de março de 2030

Consulte LICENSE para os termos completos.