MCP Android Agent

Automatize dispositivos Android usando a biblioteca uiautomator2, exigindo adb e um dispositivo conectado.

Documentação

MCP Android Agent

Este projeto fornece um servidor MCP (Model Context Protocol) para automatizar dispositivos Android usando uiautomator2. Ele foi projetado para ser facilmente integrado a agentes de IA como GitHub Copilot Chat, Claude ou Open Interpreter para controlar dispositivos Android por meio de linguagem natural.

Arquitetura Modular

O servidor foi refatorado em uma arquitetura limpa e modular, com ferramentas organizadas por funcionalidade:

mcp-android-server-python/
├── server.py                    # Main server (61 lines - clean & focused)
├── server_original_backup.py    # Backup of original monolithic version
└── tools/                       # 🆕 Modular tools package
    ├── __init__.py             # Central registration & imports
    ├── device_tools.py         # Device connection & status tools
    ├── app_tools.py            # Application management tools
    ├── screen_tools.py         # Screen control & unlock tools
    ├── input_tools.py          # User input simulation (click, swipe, text)
    ├── inspection_tools.py     # UI inspection & screenshots
    └── advanced_tools.py       # Advanced features (toast, activity wait)

Benefícios da Arquitetura Modular

Manutenibilidade: Fácil de adicionar/modificar/remover ferramentas sem tocar no servidor principal
Organização: Ferramentas agrupadas logicamente por funcionalidade
Testes: Módulos de ferramentas individuais podem ser testados unitariamente separadamente
Reutilização: Módulos de ferramentas podem ser reutilizados em outros projetos
Escalabilidade: Novas categorias de ferramentas podem ser adicionadas como módulos separados
Código Limpo: Servidor principal reduzido de 1321 linhas para 61 linhas

Demonstração Rápida

---## Requisitos

Python 3.13 ou superior
Android Debug Bridge (adb) instalado e no PATH
Dispositivo Android conectado com depuração USB habilitada
Dispositivo Android compatível com uiautomator2

Recursos

Gerenciamento de Dispositivos

Detecção Inteligente de Dispositivos: Encontra e conecta automaticamente a dispositivos disponíveis
Informações Abrangentes do Dispositivo: Obtenha serial, resolução, bateria, IP WiFi, versão do Android
Diagnósticos ADB: Verifique a disponibilidade do ADB e o status da conexão
Monitoramento de Saúde: Verificações de saúde do servidor integradas

Gerenciamento de Aplicativos

Descoberta de Aplicativos: Liste todos os aplicativos instalados (aplicativos do sistema + do usuário)
Controle do Ciclo de Vida do Aplicativo: Inicie, pare, force-stop em aplicativos pelo nome do pacote
Monitoramento de Estado do Aplicativo: Acompanhe o aplicativo e a atividade em primeiro plano
Gerenciamento de Dados: Limpe dados/cache do aplicativo para testes

Controle de Tela e Exibição

Gerenciamento de Energia da Tela: Ligue/desligue a tela programaticamente
Desbloqueio Inteligente: Desbloqueio automático da tela com métodos padrão
Monitoramento de Estado da Tela: Aguarde a ativação da tela (suporte assíncrono)

Simulação de Entrada do Usuário

Interações de Precisão: Clique por texto, ID de recurso ou descrição de conteúdo
Gestos Avançados: Clique longo, deslize, operações de arrastar
Entrada de Texto: Entrada de texto inteligente com limpeza opcional de campo
Teclas de Hardware: Simule teclas de home, voltar, menu, volume

Inspeção e Depuração de UI

Análise de Elementos: Obtenha propriedades e limites detalhados de elementos de UI
Captura de Tela: Tire capturas de tela para depuração e documentação
Hierarquia de UI: Exporte a estrutura completa da tela como XML
Espera Inteligente: Aguarde os elementos aparecerem com timeouts personalizados
Detecção de Rolagem: Role automaticamente para encontrar elementos em listas longas

Recursos Avançados

Detecção de Toast: Capture mensagens de toast do sistema para verificação
Monitoramento de Atividades: Aguarde atividades específicas do Android
Operações em Segundo Plano: Suporte assíncrono para operações demoradas

Casos de Uso

Perfeito para:

Agentes de IA que precisam interagir com dispositivos reais
Configurações de controle remoto de dispositivos
Ferramentas automatizadas de QA
Estruturas de bots Android
Testes e automação de UI
Gerenciamento e monitoramento de dispositivos

Instalação

1. Clone o repositório

git clone https://github.com/nim444/mcp-android.git
cd mcp-android

2. Crie e ative o ambiente virtual

# Using uv (https://github.com/astral-sh/uv)
uv venv
source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate

3. Instale as dependências

uv pip install

Executando o Servidor

O servidor suporta dois modos de transporte diferentes, dependendo do seu caso de uso:

Opção 1: MCP stdio (Para Integração com Agentes de IA)

Este é o modo padrão para integração com agentes de IA como Claude Desktop, VS Code ou outros clientes MCP.

# Edit server.py to use stdio mode (default commented out)
# Uncomment the stdio section and comment out http section

# Then run:
uv run python server.py

Opção 2: Streamable HTTP (Para Integração Web/API)

Este modo executa o servidor como uma API HTTP, útil para aplicações web, testes com curl ou chamadas HTTP diretas.

# Current default configuration - runs as HTTP server
uv run python server.py

# Server will be available at: http://localhost:8080

Alternando Entre Modos

Edite server.py e modifique a seção if __name__ == "__main__"::

Para o modo stdio (agentes de IA):

if __name__ == "__main__":
    mcp.run(
        transport="stdio",
        show_banner=False,
    )

Para o modo HTTP (API Web):

if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="0.0.0.0",
        port=8080,
    )

Uso

Para Integração com Agentes de IA (Claude Desktop, VS Code, etc.)

Um cliente MCP é necessário para usar este servidor. O aplicativo Claude Desktop é um exemplo de cliente MCP.

Importante: Para integração com agentes de IA, certifique-se de configurar o servidor no modo stdio (veja "Opção 1" acima).

Para usar este servidor com o Claude Desktop:

Localize o arquivo de configuração do Claude Desktop

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Adicione a configuração do servidor MCP Android à seção mcpServers

{
  "mcpServers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && uv run python server.py"
      ]
    }
  }
}

Substitua /path/to/mcp-adb pelo caminho absoluto para onde você clonou este repositório. Por exemplo: /Users/username/Projects/mcp-adb

Usando com VS Code

Você também pode usar este servidor MCP com o modo agente do VS Code (requer VS Code 1.99 ou mais recente). Para configurar:

Crie um arquivo .vscode/mcp.json no seu espaço de trabalho:

{
  "servers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && uv run python server.py"
      ]
    }
  }
}

Substitua /path/to/mcp-adb pelo caminho absoluto para onde você clonou este repositório.

Após adicionar a configuração, você pode gerenciar o servidor usando:

Paleta de Comandos → MCP: List Servers para visualizar e gerenciar servidores configurados
Paleta de Comandos → MCP: Start Server para iniciar o servidor
As ferramentas do servidor estarão disponíveis no chat do modo agente do VS Code

Para Integração com API HTTP (Chamadas Diretas de API)

Ao executar no modo HTTP (Opção 2), você pode interagir com o servidor diretamente por meio de solicitações HTTP:

# Check if server is running
curl http://localhost:8080/

# List available tools (you'll need to implement proper tool discovery endpoints)
# This depends on your FastMCP version and configuration

Casos de Uso para o Modo HTTP:

Aplicações web com automação Android
Ferramentas de teste que não podem usar stdio
Integração direta de API com outros serviços
Depuração e desenvolvimento com curl/Postman

Inspetor de UI

O projeto inclui suporte para uiauto.dev, uma poderosa ferramenta de inspeção de UI para visualizar e analisar a estrutura da interface do seu dispositivo.

Instale o inspetor de UI:

uv pip install uiautodev

Inicie o inspetor:

uiauto.dev

Abra seu navegador e acesse https://uiauto.dev

Ferramentas MCP Disponíveis

Ferramentas de Gerenciamento de Dispositivos

Tool Name	Description
`mcp_health`	Verifique se o servidor MCP está funcionando corretamente
`get_device_status`	Obtenha informações completas de status e prontidão do dispositivo
`connect_device`	Conecte-se a um dispositivo Android e obtenha informações básicas
`get_device_info`	Obtenha informações detalhadas do dispositivo: serial, resolução, bateria, etc.
`check_adb_and_list_devices`	Verifique se o ADB está instalado e liste os dispositivos conectados

Ferramentas de Gerenciamento de Aplicativos

Tool Name	Description
`get_installed_apps`	Liste todos os aplicativos instalados com versão e informações do pacote
`get_current_app`	Obtenha informações sobre o aplicativo atualmente em primeiro plano
`start_app`	Inicie um aplicativo pelo nome do pacote
`stop_app`	Pare um aplicativo pelo nome do pacote
`stop_all_apps`	Pare todos os aplicativos atualmente em execução
`clear_app_data`	Limpe os dados/cache do usuário de um aplicativo especificado

Ferramentas de Controle de Tela

Tool Name	Description
`screen_on`	Ligue a tela
`screen_off`	Desligue a tela
`unlock_screen`	Desbloqueie a tela (ligue e deslize se necessário)
`wait_for_screen_on`	Aguarde assincronamente até que a tela seja ligada

Ferramentas de Entrada do Usuário

Tool Name	Description
`press_key`	Simule pressionamento de tecla de hardware (ex.: `home`, `back`, `menu`, etc.)
`click`	Toque em um elemento por `text`, `resourceId` ou `description`
`long_click`	Execute um clique longo em um elemento
`send_text`	Insira texto no campo atualmente focado (opcionalmente limpando antes)
`swipe`	Deslize de uma coordenada para outra
`drag`	Arraste um elemento para um local específico da tela

Ferramentas de Inspeção

Tool Name	Description
`get_element_info`	Obtenha informações sobre elementos de UI (texto, limites, clicável, etc.)
`wait_for_element`	Aguarde um elemento aparecer na tela
`scroll_to`	Role até que um determinado elemento se torne visível
`screenshot`	Tire e salve uma captura de tela do dispositivo
`dump_hierarchy`	Despeje a hierarquia de UI da tela atual como XML

Ferramentas Avançadas

Tool Name	Description
`get_toast`	Obtenha a última mensagem de toast exibida na tela
`wait_activity`	Aguarde até que uma atividade específica apareça