Mobile Device MCP

Um servidor MCP para interagir com vários dispositivos iOS e Android ao mesmo tempo.

Documentação

Mobile Device MCP

Um servidor MCP que permite que agentes de IA controlem dispositivos iOS e Android (toque, rolagem, digitação, capturas de tela, leitura de árvores de UI e execução de código). Funciona com vários dispositivos ao mesmo tempo.

Como Funciona

Arquitetura em três camadas:

Servidores no dispositivo — Servidores HTTP leves executando em cada dispositivo móvel (UIAutomator no Android, XCUITest no iOS) que expõem a árvore de acessibilidade e aceitam comandos de interação.
Filtro de árvore de UI — Normaliza árvores de UI brutas de ambas as plataformas em uma lista unificada de elementos planos.
Servidor MCP — A interface externa. Gerencia descoberta de dispositivos, inicialização, alocação de portas e encaminha solicitações para servidores no dispositivo.

Os dispositivos são inicializados no primeiro uso — o servidor instala o aplicativo driver, aloca uma porta, inicia o servidor no dispositivo e faz polling até que esteja saudável. Depois disso, todas as chamadas de ferramentas são encaminhadas via HTTP localhost com autenticação por token bearer por dispositivo.

Ferramentas

Ferramenta	Descrição
`list_devices`	Lista dispositivos iOS e Android disponíveis
`screenshot`	Captura a tela do dispositivo (JPEG)
`uitree`	Obtém a árvore de elementos de UI como uma lista plana, com busca e limite opcionais. Elementos fora da tela são excluídos, a menos que `include_invisible: true`
`tap`	Toque nas coordenadas da tela
`double_tap`	Toque duplo nas coordenadas da tela
`long_press`	Toque longo nas coordenadas da tela (duração configurável)
`scroll`	Deslize das coordenadas iniciais para as finais
`type_text`	Digita texto no elemento focado
`press_button`	Pressiona um botão de hardware/navegação (home, voltar, enter, volumeUp/Down, dpadUp/Down/Left/Right/Center)
`launch_app`	Inicia um aplicativo pelo ID do bundle / nome do pacote
`terminate_app`	Força a parada de um aplicativo
`list_apps`	Lista aplicativos instalados
`install_app`	Instala um aplicativo a partir de um arquivo local do host (`.apk` para Android, `.app` para simulador iOS, `.app`/`.ipa` para dispositivo iOS). Substitui instalações existentes
`run_code`	Executa JavaScript em sandbox no dispositivo (veja run_code abaixo)

run_code

Agentes podem passar código que parece UIAutomator ou XCUITest, ambos sendo JavaScript por baixo dos panos. O sandbox restringe (Android) operações Java potencialmente perigosas e permite apenas (iOS) alguns comandos semelhantes a XCUITest

Android: Motor Rhino com bindings UIAutomator — uiDevice (clique, deslize, encontre elementos, pressione teclas, leia informações de exibição), By (seletores), Until (condições de espera), console.log()
iOS: JavaScriptCore com bindings XCUITest — app (consulte elementos, toque, digite, deslize), springboard, device, openApp(bundleId), sleep(ms), console.log()

Ambas as plataformas matam automaticamente scripts descontrolados (loops infinitos) e criam um sandbox novo por chamada.

Pré-requisitos

Node.js 18+ (para execução via npx)
Android: Android SDK com adb no PATH
Simulador iOS: Xcode com xcrun, simctl
Dispositivo iOS Real: Xcode com xcodebuild, devicectl, e iproxy (de libimobiledevice)
Compilação a partir do código-fonte: runtime Bun, Gradle (Android), Xcode (iOS)

Instalação

Claude Code

claude mcp add mobile-device-mcp -- npx -y @srmorete/mobile-device-mcp@latest

Ou com portas personalizadas:

claude mcp add mobile-device-mcp -e MDMS_PORT_ANDROID=20000 -e MDMS_PORT_IOS=21000 -- npx -y @srmorete/mobile-device-mcp@latest

Modificando `.mcp.json` (Cursor, Claude Desktop, etc)

{
  "mcpServers": {
    "mobile-device-mcp": {
      "command": "npx",
      "args": ["-y", "@srmorete/mobile-device-mcp@latest"],
      "env": {
        "MDMS_PORT_ANDROID": "18000",           # optional
        "MDMS_PORT_IOS": "19000"                # optional
      }
    }
  }
}

Compilação a partir do Código-Fonte

git clone <repo-url>
cd mobile-device-mcp
bun install

# Build drivers for both platforms and pack tarball
./scripts/build.sh

O script de compilação compila os drivers no dispositivo (APKs Android via Gradle, pacote de teste iOS via xcodebuild), copia-os para drivers/, e cria um tarball npm.

Para executar localmente durante o desenvolvimento:

bun run start           # Start the MCP server
bun test                # Run the test suite

Configuração

Variável de Ambiente	Padrão	Descrição
`MDMS_PORT_ANDROID`	18000	Porta base para servidores Android no dispositivo
`MDMS_PORT_IOS`	19000	Porta base para servidores iOS no dispositivo

As portas são atribuídas sequencialmente — o primeiro dispositivo Android recebe 18000, o segundo recebe 18001, e assim por diante. O mesmo para iOS começando em 19000.

Agradecimentos

O servidor Mobile Device MCP se apoia em gigantes como mobile-mcp e Maestro. Usados como inspiração, mas reformulamos a abordagem atual para ser multi-dispositivo e com suporte nativo/WebView contínuo (especialmente no Android).

Licença

MIT

Mobile Device MCP

Documentação