MobAI MCP

Servidor MobAI MCP

Servidor MCP (Model Context Protocol) para MobAI — automação de dispositivos móveis com IA. Permite que assistentes de IA (Claude Code, Cursor, Windsurf, Cline e outras ferramentas compatíveis com MCP) controlem dispositivos Android e iOS, emuladores e simuladores por meio de uma interface única baseada em DSL.

Como funciona

Toda interação com o dispositivo é agrupada em uma ferramenta principal: execute_dsl. Em vez de expor dezenas de ferramentas granulares (toque, deslize, digitação…), o servidor aceita um script JSON que descreve uma sequência de ações com predicados, asserções, esperas e ramificações condicionais. Isso mantém o número de idas e voltas baixo e codifica estratégias de repetição/falha no lado do servidor.

Um pequeno conjunto de ferramentas complementares lida com descoberta de dispositivos, capturas de tela, gerenciamento de aplicativos e execução de arquivos de teste .mob.

Pré-requisitos

• Node.js 18+
• Aplicativo de desktop MobAI em execução localmente (API HTTP em 127.0.0.1:8686)
• Um dispositivo Android ou iOS, emulador ou simulador conectado

Instalação

Claude Code

claude mcp add mobai -- npx -y mobai-mcp

Cursor

Adicione a .cursor/mcp.json:

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

Claude Desktop

Adicione a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Windsurf / Cline / outros clientes MCP

O servidor usa stdio — use a configuração MCP genérica do seu cliente:

{
  "command": "npx",
  "args": ["-y", "mobai-mcp"]
}

Ferramentas

Gerenciamento de dispositivos

Ferramenta	Descrição
list_devices	Lista todos os dispositivos Android e iOS conectados
get_device	Obtém detalhes sobre um dispositivo específico
start_bridge	Inicia a ponte de automação em um dispositivo (necessário antes da interação)
stop_bridge	Interrompe a ponte de automação
claim_device	Reivindica uso exclusivo de um dispositivo para esta sessão (geralmente opcional: agir em um dispositivo não reivindicado o reivindica automaticamente)
release_device	Libera uma ou todas as concessões de dispositivo mantidas por esta sessão

Capturas de tela

Ferramenta	Descrição
get_screenshot	Captura de tela rápida e de baixa qualidade para análise visual por LLM (pode ser reduzida; a resposta inclui o fator de escala)
save_screenshot	PNG em qualidade total para disco, para relatórios, depuração ou compartilhamento

Aplicativos

Ferramenta	Descrição
list_apps	Lista os aplicativos instalados no dispositivo
install_app	Instala um .apk ou .ipa a partir de um caminho de arquivo local
uninstall_app	Desinstala um aplicativo por ID do pacote / nome do pacote
debug_app	Inicia um aplicativo em modo de depuração e grava stdout/stderr em um arquivo de log

Automação

Ferramenta	Descrição
execute_dsl	Ferramenta principal. Executa um lote de etapas DSL: toque, digitação, deslize, observação, asserções, automação web, métricas, gravação de tela e muito mais.

Gerenciamento de testes

Os testes são arquivos .mob em disco dentro de diretórios de projeto. Você os lê, escreve e edita diretamente usando as ferramentas de sistema de arquivos do seu assistente — o MobAI observa as alterações e atualiza a interface ao vivo. O MCP é necessário apenas para descobrir projetos e executar testes.

Ferramenta	Descrição
test_get_active	Obtém o diretório do projeto de teste ativo e seus casos .mob
test_list_projects	Lista todos os diretórios de projeto de teste conhecidos com seus casos .mob
test_run	Executa um caso de teste .mob em um dispositivo (project_dir + case_path + device_id, params opcional para substituição de ${name})

Recursos

Leia estes antes de tentar qualquer interação com o dispositivo — eles descrevem o esquema DSL, o conjunto de ações, predicados, estratégias de falha e a sintaxe .mob.

URI	Finalidade
mobai://reference/device-automation	Como controlar dispositivos — guia, todas as ações DSL, predicados e estratégias de falha
mobai://reference/testing	Fluxo de trabalho de testes, regras, correções de erros e sintaxe de script .mob

Exemplo

Abra o aplicativo Ajustes do iOS, navegue até Wi-Fi e verifique se o botão de alternância existe:

{
  "version": "0.2",
  "steps": [
    {"action": "open_app", "bundle_id": "com.apple.Preferences"},
    {"action": "wait_for", "predicate": {"text": "Settings"}, "timeout_ms": 3000},
    {"action": "tap", "predicate": {"text_contains": "Wi-Fi"}},
    {"action": "wait_for", "predicate": {"type": "switch"}, "timeout_ms": 3000},
    {"action": "assert_exists", "predicate": {"type": "switch"}},
    {"action": "observe", "include": ["ui_tree"]}
  ]
}

Passe isso como o argumento commands (uma string JSON) para execute_dsl junto com um device_id de list_devices.

Solução de problemas

"Connection refused" / "Could not reach the MobAI desktop app" — Certifique-se de que o aplicativo de desktop MobAI esteja instalado e em execução, e que a API esteja acessível em http://127.0.0.1:8686. Se você ainda não o tiver, baixe e instale-o em https://mobai.run/download.

"Bridge not running" — Chame start_bridge primeiro. A ponte iOS pode levar até um minuto para ficar pronta.

Capturas de tela não visíveis — get_screenshot salva em /tmp/mobai/screenshots/ por padrão e retorna o caminho do arquivo. Use o recurso de leitura de arquivos do seu assistente para visualizá-las. As capturas de tela DSL observe são extraídas da resposta e salvas no mesmo diretório.

Desenvolvimento

git clone https://github.com/MobAI-App/mobai-mcp.git
cd mobai-mcp
npm install
npm run build
node dist/index.js

Licença

Apache 2.0 — consulte LICENSE.