Mobile MCP: como conectar Claude Code, Codex e Cursor aos seus apps mobile

O Mobile MCP conecta agentes de IA a aplicações iOS e Android. Em vez de depender de um screenshot para entender cada tela, o agente consulta a árvore de acessibilidade e interage com os elementos disponíveis.

Na prática, isso permite que ferramentas como Claude Code, Codex e Cursor localizem botões, campos, textos e outros elementos da interface para executar ações no app. O repositório descreve a abordagem como “no vision model, no image tokens”: a interação principal acontece pela estrutura acessível da tela, não pelo envio contínuo de imagens.

O comportamento final depende do seu app, do ambiente de execução e da qualidade da acessibilidade implementada. Por isso, trate o Mobile MCP como uma ponte de controle e teste o fluxo completo antes de usar em automações importantes.

O Mobile MCP não elimina as ferramentas nativas de desenvolvimento mobile. Para testar iOS, você precisa ter Xcode. Para Android, precisa ter as Android Platform Tools disponíveis no ambiente.

• iOS: prepare o Xcode e um simulador ou dispositivo compatível com o fluxo que você deseja testar.
• Android: instale as Android Platform Tools e deixe o emulador ou dispositivo acessível por elas.
• Agente: use Claude Code, Codex ou Cursor com suporte a servidores MCP.
• Aplicação: verifique se o app expõe corretamente seus elementos pela acessibilidade.

Há uma limitação importante: quando o app não oferece uma árvore de acessibilidade utilizável, o Mobile MCP pode cair para o modo screenshot. Portanto, “sem screenshot” não é uma garantia para qualquer aplicação; é o caminho preferencial quando a interface fornece os dados necessários.

Com o Claude Code instalado, adicione o servidor MCP usando o comando indicado no README do projeto:

claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest

1. Abra o terminal na máquina em que o Claude Code será executado.
2. Rode o comando de instalação.
3. Inicie ou reabra o Claude Code para que a configuração seja carregada.
4. Confirme, na lista de servidores MCP, que o mobile-mcp está disponível.
5. Conecte o simulador ou dispositivo e peça ao agente para inspecionar o app.

Se o comando não funcionar, consulte o README do repositório para conferir a sintaxe atual, a versão do pacote e os requisitos do seu sistema.

No Codex, o servidor pode ser adicionado pelo comando de configuração MCP:

codex mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest

1. Execute o comando no terminal em que o Codex está configurado.
2. Abra uma nova sessão do Codex, se necessário.
3. Confira se o servidor aparece entre as integrações MCP disponíveis.
4. Com o ambiente mobile pronto, peça uma ação simples, como listar os elementos acessíveis da tela atual.
5. Só depois avance para ações que alterem dados ou naveguem por vários passos.

O primeiro teste deve ser de leitura. Assim você consegue separar um problema de conexão MCP de um problema na acessibilidade ou no estado do aplicativo.

No Cursor, adicione o servidor MCP pela configuração de MCP do editor usando o comando do pacote:

npx -y @mobilenext/mobile-mcp@latest

1. Abra as configurações de MCP do Cursor.
2. Crie ou edite a entrada do servidor chamada mobile-mcp.
3. Informe npx como comando e use -y @mobilenext/mobile-mcp@latest como argumentos, conforme a configuração mostrada no README.
4. Salve a configuração e reinicie ou recarregue o Cursor.
5. Verifique se o servidor está conectado antes de executar ações no app.

Como as telas de configuração podem mudar entre versões do Cursor, use o exemplo atualizado do repositório como fonte de verdade para o formato do arquivo.

Depois da instalação, não comece pedindo uma sequência complexa. Faça um teste curto para verificar se o agente consegue enxergar e manipular a interface:

1. Abra o simulador ou dispositivo.
2. Inicie o app na tela que deseja testar.
3. Peça ao agente para descrever os elementos acessíveis visíveis.
4. Solicite uma ação reversível, como tocar em um botão de navegação ou preencher um campo de teste.
5. Confirme no dispositivo se a ação realmente aconteceu.
6. Repita o fluxo com uma tela diferente e compare o resultado.

Exemplo de instrução: “Inspecione a tela atual pela árvore de acessibilidade, identifique o botão de entrada e descreva o que você encontrou antes de tocar nele.”

Essa abordagem reduz o risco de o agente agir sobre o elemento errado e ajuda a identificar rapidamente se o problema está no MCP, no ambiente mobile ou na implementação de acessibilidade.

O Mobile MCP depende do que o sistema consegue expor sobre a interface. Um botão sem nome, um campo sem rótulo ou uma hierarquia confusa pode dificultar a localização do elemento pelo agente.

• Dê nomes claros aos controles interativos.
• Use rótulos que descrevam a ação, não apenas a aparência.
• Evite elementos visualmente diferentes com o mesmo nome acessível.
• Teste estados importantes, como carregando, desabilitado, erro e sucesso.
• Verifique se os elementos relevantes aparecem na árvore quando a tela está pronta para interação.

Se o agente não encontrar um elemento, não conclua imediatamente que a integração falhou. Primeiro verifique se o elemento está realmente acessível no iOS ou no Android.

O README afirma a abordagem “no vision model, no image tokens”, mas não há, no material do post, um benchmark publicado de economia que possa ser aplicado a qualquer aplicação. Portanto, não trate uma economia específica como garantida.

Faça sua própria medição comparando fluxos equivalentes:

• Registre quantos passos o agente executa até concluir a tarefa.
• Observe quando ele usa a árvore de acessibilidade e quando recorre ao screenshot.
• Compare a duração do fluxo e a quantidade de falhas.
• Verifique se o agente precisou repetir ações ou pedir esclarecimentos.
• Meça o consumo de tokens no ambiente que você utiliza, se essa informação estiver disponível.

Use tarefas reais do seu app, como login em ambiente de teste, navegação entre telas ou preenchimento de um formulário. O resultado pode variar bastante conforme a estrutura da aplicação e a qualidade dos elementos acessíveis.

Use esta lista antes de considerar a integração pronta:

• O repositório correto foi instalado: mobile-next/mobile-mcp.
• O Xcode está disponível para o fluxo iOS.
• As Android Platform Tools estão disponíveis para o fluxo Android.
• O simulador ou dispositivo está conectado e com o app aberto.
• O servidor mobile-mcp aparece conectado no seu cliente.
• O agente consegue listar ou descrever elementos da tela.
• Uma ação simples e reversível foi executada com sucesso.
• As telas críticas foram testadas pela acessibilidade.
• Os fluxos foram medidos no seu próprio app, sem assumir um benchmark genérico.

Comece por um ambiente de teste e por ações que possam ser desfeitas. Depois, amplie gradualmente a cobertura.