Android MCP

Servidor Android MCP

Um servidor MCP (Model Context Protocol) que fornece controle programático sobre dispositivos Android através do ADB (Android Debug Bridge). Este servidor expõe várias capacidades de gerenciamento de dispositivos Android que podem ser acessadas por clientes MCP como Claude desktop e editores de código (por exemplo, Cursor)

Recursos

• 🔧 Execução de Comandos ADB
• 📸 Captura de Tela do Dispositivo
• 🎯 Análise de Layout de UI
• 📱 Gerenciamento de Pacotes do Dispositivo

Pré-requisitos

• Python 3.x
• ADB (Android Debug Bridge) instalado e configurado
• Dispositivo Android ou emulador (não testado)

Instalação

1. Clone o repositório:

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

2. Instale as dependências: Este projeto usa uv para gerenciamento de projeto através de vários métodos de instalação.

uv python install 3.11
uv sync

Configuração

O servidor suporta configuração flexível de dispositivos com múltiplos cenários de uso.

Modos de Seleção de Dispositivo

1. Seleção Automática (Recomendado para dispositivo único)

• Nenhum arquivo de configuração necessário
• Conecta-se automaticamente ao único dispositivo conectado
• Perfeito para desenvolvimento com um único dispositivo de teste

2. Seleção Manual de Dispositivo

• Use quando tiver múltiplos dispositivos conectados
• Especifique o dispositivo exato no arquivo de configuração

Arquivo de Configuração (Opcional)

O arquivo de configuração (config.yaml) é opcional. Se não estiver presente, o servidor selecionará automaticamente o dispositivo se apenas um estiver conectado.

Para Seleção Automática

Basta garantir que apenas um dispositivo esteja conectado e executar o servidor - nenhuma configuração necessária!

Para Seleção Manual

1. Crie um arquivo de configuração:

cp config.yaml.example config.yaml

2. Edite config.yaml e especifique seu dispositivo:

device:
  name: "your-device-serial-here" # Device identifier from 'adb devices'

Para seleção automática, você pode usar qualquer um destes métodos:

device:
  name: null              # Explicit null (recommended)
  # name: ""              # Empty string  
  # name:                 # Or leave empty/comment out

Encontrando o Serial do Seu Dispositivo

Para encontrar o identificador do seu dispositivo, execute:

adb devices

Exemplo de saída:

List of devices attached
13b22d7f        device
emulator-5554   device

Use o valor da primeira coluna (por exemplo, 13b22d7f ou emulator-5554) como o nome do dispositivo.

Cenários de Uso

Cenário	Configuração Necessária	Comportamento
Dispositivo único conectado	Nenhuma	✅ Conecta-se automaticamente ao dispositivo
Múltiplos dispositivos, deseja um específico	config.yaml com device.name	✅ Conecta-se ao dispositivo especificado
Múltiplos dispositivos, sem configuração	Nenhuma	❌ Mostra erro com dispositivos disponíveis
Nenhum dispositivo conectado	N/A	❌ Mostra erro "nenhum dispositivo"

Nota: Se você tiver múltiplos dispositivos conectados e não especificar qual usar, o servidor mostrará uma mensagem de erro listando todos os dispositivos disponíveis.

Uso

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

1. 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

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

{
  "mcpServers": {
    "android": {
      "command": "path/to/uv",
      "args": ["--directory", "path/to/android-mcp-server", "run", "server.py"]
    }
  }
}

Substitua:

• path/to/uv pelo caminho real para o seu executável uv
• path/to/android-mcp-server pelo caminho absoluto para onde você clonou este repositório

https://github.com/user-attachments/assets/c45bbc17-f698-43e7-85b4-f1b39b8326a8

Ferramentas Disponíveis

O servidor expõe as seguintes ferramentas:

def get_packages() -> str:
    """
    Get all installed packages on the device.
    Returns:
        str: A list of all installed packages on the device as a string
    """

def execute_adb_command(command: str) -> str:
    """
    Executes an ADB command and returns the output.
    Args:
        command (str): The ADB command to execute
    Returns:
        str: The output of the ADB command
    """

def get_uilayout() -> str:
    """
    Retrieves information about clickable elements in the current UI.
    Returns a formatted string containing details about each clickable element,
    including their text, content description, bounds, and center coordinates.

    Returns:
        str: A formatted list of clickable elements with their properties
    """

def get_screenshot() -> Image:
    """
    Takes a screenshot of the device and returns it.
    Returns:
        Image: the screenshot
    """

def get_package_action_intents(package_name: str) -> list[str]:
    """
    Get all non-data actions from Activity Resolver Table for a package
    Args:
        package_name (str): The name of the package to get actions for
    Returns:
        list[str]: A list of all non-data actions from the Activity Resolver
        Table for the package
    """

Contribuindo

Contribuições são bem-vindas!

Agradecimentos

• Construído com Model Context Protocol (MCP)