Android MCP Server

Controla dispositivos Android a través del Android Debug Bridge (ADB).

GitHub
3

Documentación

Android MCP Server

Resumen

Este repositorio proporciona un servidor MCP (Model Context Protocol) para el control de dispositivos Android a través de ADB (Android Debug Bridge). Expone herramientas simples (funciones) que pueden ser llamadas desde LLMs o clientes (como Claude Desktop) para automatizar acciones en dispositivos Android, como abrir Chrome y realizar una búsqueda.

El objetivo es facilitar que cualquier cliente compatible con MCP (como Claude Desktop) controle un dispositivo Android usando lenguaje natural y herramientas seguras y auditables.

Características

  • open_chrome_and_search:
    Abre el navegador predeterminado en un dispositivo Android conectado y realiza una búsqueda de Google para una consulta dada.
  • screenshot_and_preprocess:
    Toma una captura de pantalla y la preprocesa para su uso posterior.
  • send_sms_via_adb:
    Envía un mensaje SMS a través de ADB a un número especificado.
  • get_device_model:
    Obtiene el nombre del modelo del dispositivo Android conectado.
  • get_battery_info:
    Devuelve el estado y la información de la batería.
  • get_device_features:
    Lista las características de hardware/software compatibles con el dispositivo.
  • get_storage_info:
    Proporciona información sobre el uso del almacenamiento del dispositivo.
  • get_network_info:
    Devuelve detalles sobre la conectividad de red del dispositivo.
  • take_screenshot:
    Captura una captura de pantalla del dispositivo.
  • open_settings:
    Abre la aplicación de configuración principal en el dispositivo.
  • toggle_airplane_mode:
    Activa o desactiva el modo avión.
  • increase_volume / decrease_volume:
    Ajusta el volumen multimedia del dispositivo hacia arriba o hacia abajo.
  • press_power_button:
    Simula presionar el botón de encendido.
  • press_home_button:
    Simula presionar el botón de inicio.
  • press_back_button:
    Simula presionar el botón de retroceso.
  • open_wifi_settings:
    Abre la pantalla de configuración de Wi-Fi.
  • open_bluetooth_settings:
    Abre la pantalla de configuración de Bluetooth.
  • open_display_settings:
    Abre la pantalla de configuración de pantalla.
  • Fácilmente extensible: agrega más herramientas basadas en ADB según sea necesario (lanzar aplicaciones, tomar capturas de pantalla, etc.)
  • Seguro: solo expone acciones específicas y permitidas.

Requisitos

  • Python 3.10+
  • ADB instalado y agregado a tu PATH del sistema
  • Un dispositivo Android con:
    • Modo desarrollador habilitado
    • Depuración USB habilitada
  • Claude Desktop (o cualquier cliente compatible con MCP)
  • uv herramienta de proyecto Python (recomendada, pero puedes adaptarla a pip/venv si lo deseas)

Instalación y Configuración

1. Clonar el repositorio

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

cd android-mcp-server

2. Instalar uv (si aún no lo tienes)

En Windows (PowerShell):

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

En Mac/Linux:

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

Reinicia tu terminal después de la instalación.

3. Configurar el entorno de Python

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

uv add "mcp[cli]"

4. (Opcional) Probar el servidor manualmente

uv run android_server.py

El servidor esperará conexiones de clientes MCP.

Uso: Integrar con Claude Desktop

Para conectar tu servidor MCP a Claude Desktop:

1. Asegúrate de que Claude Desktop esté instalado y completamente actualizado.

2. Editar/Crear el archivo de configuración de Claude

En Windows:

  • Ubicación:
    C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json

En Mac:

  • Ubicación:
    ~/Library/Application Support/Claude/claude_desktop_config.json

Crea el archivo si no existe.

3. Agregar tu configuración del servidor

Configuración de ejemplo (actualiza la ruta del directorio si clonaste en otro lugar):

{
  "mcpServers": {
    "android_control": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\<YourUsername>\\Desktop\\android-mcp-server",
        "run",
        "android_server.py"
      ]
    }
  }
}
  • Usa la ruta absoluta a tu carpeta de proyecto.
  • Guarda el archivo de configuración.

4. Reiniciar Claude Desktop

  • Cierra completamente todas las ventanas de Claude Desktop (incluido el icono de la bandeja).
  • Vuelve a abrir Claude Desktop.

5. Conecta tu dispositivo Android

  • Habilita las Opciones de desarrollador y la Depuración USB en tu teléfono.
  • Conéctalo por USB.
  • Acepta cualquier aviso de "Permitir depuración USB".

Ejemplo de uso

En Claude Desktop, ahora puedes usar la herramienta escribiendo un mensaje en lenguaje natural como:

  • "Busca 'últimas noticias de Android' en mi dispositivo Android."
  • "Usa la herramienta open_chrome_and_search con la consulta: tutoriales de Python"

Claude invocará la herramienta, y el navegador de tu teléfono se abrirá y realizará la búsqueda.

Agregar más herramientas

Para ampliar la funcionalidad, simplemente agrega más funciones de Python decoradas con @mcp.tool() a android_server.py.
Por ejemplo, puedes agregar herramientas para tomar una captura de pantalla, instalar una aplicación, abrir una aplicación específica, etc.

Solución de problemas

  • ¿No se encuentra el dispositivo?
    Asegúrate de haber ejecutado adb devices y de ver tu dispositivo en la lista.
  • ¿El servidor MCP no aparece en Claude?
    Vuelve a verificar la ruta y la sintaxis de tu archivo de configuración, y reinicia Claude Desktop.
  • ¿Errores inesperados de token o JSON?
    Asegúrate de que NO haya declaraciones print ni registros en stdout en el código de tu servidor; todas las salidas deben ir únicamente a través de llamadas MCP.
  • ¿Sigue atascado?
    Revisa los registros de Claude (botón en la interfaz de Claude Desktop) para obtener detalles.

Créditos