Android MCP Server

Controle dispositivos Android via o Android Debug Bridge (ADB).

Documentação

Android MCP Server

Visão Geral

Este repositório fornece um servidor MCP (Model Context Protocol) para controle de dispositivos Android via ADB (Android Debug Bridge). Ele expõe ferramentas simples (funções) que podem ser chamadas por LLMs ou clientes (como o Claude Desktop) para automatizar ações em dispositivos Android, como abrir o Chrome e realizar uma pesquisa.

O objetivo é facilitar que qualquer cliente compatível com MCP (como o Claude Desktop) controle um dispositivo Android usando linguagem natural e ferramentas seguras e auditáveis.

Recursos

open_chrome_and_search:
Abre o navegador padrão em um dispositivo Android conectado e realiza uma pesquisa no Google para uma consulta fornecida.
screenshot_and_preprocess:
Tira uma captura de tela e a pré-processa para uso posterior.
send_sms_via_adb:
Envia uma mensagem SMS via ADB para um número especificado.
get_device_model:
Obtém o nome do modelo do dispositivo Android conectado.
get_battery_info:
Retorna o status e as informações da bateria.
get_device_features:
Lista os recursos de hardware/software suportados pelo dispositivo.
get_storage_info:
Fornece informações sobre o uso do armazenamento do dispositivo.
get_network_info:
Retorna detalhes sobre a conectividade de rede do dispositivo.
take_screenshot:
Captura uma captura de tela do dispositivo.
open_settings:
Abre o aplicativo de configurações principal no dispositivo.
toggle_airplane_mode:
Ativa ou desativa o modo avião.
increase_volume / decrease_volume:
Ajusta o volume de mídia do dispositivo para cima ou para baixo.
press_power_button:
Simula o pressionamento do botão de energia.
press_home_button:
Simula o pressionamento do botão inicial.
press_back_button:
Simula o pressionamento do botão voltar.
open_wifi_settings:
Abre a tela de configurações de Wi-Fi.
open_bluetooth_settings:
Abre a tela de configurações de Bluetooth.
open_display_settings:
Abre a tela de configurações de exibição.
Facilmente extensível: adicione mais ferramentas baseadas em ADB conforme necessário (iniciar aplicativos, tirar capturas de tela, etc.)
Seguro: expõe apenas ações específicas e na lista de permissões.

Requisitos

Python 3.10+
ADB instalado e adicionado ao PATH do seu sistema
Um dispositivo Android com:
- Modo desenvolvedor ativado
- Depuração USB ativada
Claude Desktop (ou qualquer cliente compatível com MCP)
uv ferramenta de projeto Python (recomendado, mas você pode adaptar para pip/venv se preferir)

Instalação e Configuração

1. Clone o repositório

git clone https://github.com/IngaleChinmay04/android-mcp-server

cd android-mcp-server

2. Instale o uv (se ainda não tiver)

No Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

No Mac/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Reinicie o terminal após a instalação.

3. Configure o ambiente Python

uv venv
# On Windows:
.venv\Scripts\activate
# On Mac/Linux:
source .venv/bin/activate

uv add "mcp[cli]"

4. (Opcional) Teste o servidor manualmente

uv run android_server.py

O servidor aguardará conexões de clientes MCP.

Uso: Integração com o Claude Desktop

Para conectar seu servidor MCP ao Claude Desktop:

1. Certifique-se de que o Claude Desktop esteja instalado e totalmente atualizado.

2. Edite/Crie o arquivo de configuração do Claude

No Windows:

Localização:
C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json

No Mac:

Localização:
~/Library/Application Support/Claude/claude_desktop_config.json

Crie o arquivo se ele não existir.

3. Adicione a configuração do seu servidor

Exemplo de configuração (atualize o caminho do diretório se você clonou em outro local):

{
  "mcpServers": {
    "android_control": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\<YourUsername>\\Desktop\\android-mcp-server",
        "run",
        "android_server.py"
      ]
    }
  }
}

Use o caminho absoluto para a pasta do seu projeto.
Salve o arquivo de configuração.

4. Reinicie o Claude Desktop

Feche completamente todas as janelas do Claude Desktop (incluindo o ícone da bandeja).
Reabra o Claude Desktop.

5. Conecte seu dispositivo Android

Ative as Opções do Desenvolvedor e a Depuração USB no seu telefone.
Conecte via USB.
Aceite qualquer prompt "Permitir Depuração USB".

Exemplo de Uso

No Claude Desktop, agora você pode usar a ferramenta digitando um prompt em linguagem natural, como:

"Pesquise 'últimas notícias do Android' no meu dispositivo Android."
"Use a ferramenta open_chrome_and_search com a consulta: Tutoriais de Python"

O Claude invocará a ferramenta, e o navegador do seu telefone abrirá e realizará a pesquisa.

Adicionando Mais Ferramentas

Para estender a funcionalidade, basta adicionar mais funções Python decoradas com @mcp.tool() em android_server.py.
Por exemplo, você pode adicionar ferramentas para tirar uma captura de tela, instalar um aplicativo, abrir um aplicativo específico, etc.

Solução de Problemas

Nenhum dispositivo encontrado?
Certifique-se de ter executado adb devices e veja seu dispositivo listado.
O servidor MCP não aparece no Claude?
Verifique novamente o caminho e a sintaxe do arquivo de configuração e reinicie o Claude Desktop.
Erros inesperados de token/JSON?
Garanta que NÃO haja instruções print ou registro em stdout no código do seu servidor; todas as saídas devem passar apenas por chamadas MCP.
Ainda com problemas?
Verifique os logs do Claude (botão na interface do Claude Desktop) para obter detalhes.

Android MCP Server

Documentação