Neem2004/android-mcp-server

GitHub Sponsors

English · Español

---

English

Description

Android ADB MCP Server is a Model Context Protocol (MCP) server that lets AI assistants — such as Claude and OpenCode, or VS Code through its Copilot/agent integration — control Android devices over ADB securely. It exposes tools to read logcat, inspect the current UI hierarchy, list installed packages, and run restricted shell commands, all gated by an allowlist that mitigates arbitrary command execution.

A note on terminology: Claude and OpenCode are AI assistants. VS Code is not an AI — it is a code editor that hosts AI assistants (GitHub Copilot, and MCP-capable extensions) and is itself an MCP client. The server works with any MCP-capable client.

Prerequisites

• Node.js v18+ (tested up to Node.js 26).
• ADB installed and reachable via the system PATH (adb version must work), or located via ADB_PATH / ANDROID_HOME / standard SDK paths.
• USB debugging enabled on the Android device (Developer options → USB debugging).

Installation & Usage

1. Clone & install dependencies

git clone https://github.com/Neem2004/android-mcp-server.git
cd android-mcp-server
npm install

2. Build

npm run build

This produces the compiled code in the dist/ folder.

⚠️ Important: dist/ is generated locally and is not committed to the repository. You must run npm run build before configuring your MCP client, or the server will fail to start.

💡 Quick start (published on npm): you can skip the clone and build entirely — the server is published as @neem2004/android-mcp-server and includes the compiled dist/. Run it directly with npx -y @neem2004/android-mcp-server, as shown in the configs below. The absolute path form targets a local clone (replace YOUR_PATH_TO with its location).

3. Configure your MCP client

Each MCP client keeps its servers in a different file, with a different format. Below are the three most common setups, each with the published-package form (npx) and the local-clone alternative.

OpenCode (AI assistant / CLI)

File: opencode.json at your project root, or ~/.config/opencode/opencode.json (global).

{
  "mcp": {
    "android": {
      "type": "local",
      "command": ["npx", "-y", "@neem2004/android-mcp-server"],
      "enabled": true
    }
  }
}

Local clone alternative — "command": ["node", "YOUR_PATH_TO/android-mcp-server/dist/index.js"].

Claude Desktop (AI assistant)

File: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["-y", "@neem2004/android-mcp-server"]
    }
  }
}

Local clone alternative — "command": "node" with "args": ["YOUR_PATH_TO/android-mcp-server/dist/index.js"].

VS Code (editor with Copilot / MCP agent support)

File: .vscode/mcp.json in your workspace (or via the MCP: Open User Configuration command). VS Code uses servers as the top-level key (not mcpServers).

{
  "servers": {
    "android": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@neem2004/android-mcp-server"]
    }
  }
}

Local clone alternative — "command": "node" with "args": ["YOUR_PATH_TO/android-mcp-server/dist/index.js"].

Development note: instead of the compiled build you can run TypeScript directly via tsx by replacing the argument with src/index.ts and using npx tsx as the command. Prefer the compiled build for reliability.

4. Basic validation

npm test           # runs the unit test suite
npm run build      # compiles TypeScript to dist/
npm run dev        # runs the server directly via tsx (development)

Available Tools

Tool	Description	Arguments
adb_get_logcat	Dumps the logcat buffer with optional filters	lines, filter_tag, log_level
adb_clear_logcat	Clears the device log buffer	—
adb_dump_hierarchy	Returns the current UI hierarchy (XML/text)	—
adb_list_packages	Lists installed packages	filter, include_system
adb_execute_shell	Runs a safe allowlisted shell command	command

Security

This server prioritizes safety over arbitrary command execution:

• Shell allowlist: adb_execute_shell only accepts commands whose prefix is authorized (getprop, dumpsys, pm list). Anything else is rejected with a descriptive error. Command chaining (&&, ||, ;, |) and injection metacharacters are also blocked.
• No root: no superuser privileges are requested; it works on standard ADB APIs.
• Commands run via execFile (no intermediate shell), avoiding metacharacter injection.

The logic lives in src/adb/security.ts; review it before broadening permissions.

Setting Up ADB

If you do not have ADB yet:

• Windows: download the official platform-tools and add its folder to your system PATH.
• macOS / Linux: install via your package manager (e.g. brew install android-platform-tools, apt install adb).

Verify with:

adb devices

Your device should appear as device (not unauthorized/offline). The server will use ADB_PATH, then ANDROID_HOME/ANDROID_SDK_ROOT, then standard SDK locations, before falling back to adb on the PATH.

Sponsorship

This project is 100% open source and independently maintained. If Android ADB MCP Server saves your team time or improves your automation workflows, please consider supporting its continued development.

• 🔗 GitHub Sponsors: Sponsor Neem2004
• 💼 Companies: corporate sponsorship funds new tools, security hardening, and priority support.

Every contribution, however small, helps keep the project active, documented, and secure. Thank you for your support!

License

ISC

---

Español

Descripción

Android ADB MCP Server es un servidor del Model Context Protocol (MCP) que permite a asistentes de IA —como Claude y OpenCode, o VS Code mediante su integración con Copilot/agente— controlar dispositivos Android vía ADB de forma segura. Expone herramientas para leer el logcat, inspeccionar la jerarquía de la UI, listar paquetes instalados y ejecutar comandos shell restringidos, todo a través de una lista blanca que mitiga los riesgos de ejecución arbitraria.

Nota sobre terminología: Claude y OpenCode son asistentes de IA. VS Code no es una IA — es un editor de código que aloja asistentes de IA (GitHub Copilot y extensiones con soporte MCP) y que además es un cliente MCP. El servidor funciona con cualquier cliente compatible con MCP.

Requisitos previos

• Node.js v18+ (probado hasta Node.js 26).
• ADB instalado y accesible en el PATH del sistema (adb version debe funcionar), o localizado vía ADB_PATH / ANDROID_HOME / rutas estándar del SDK.
• Depuración USB activada en el dispositivo Android (Opciones de desarrollador → Depuración USB).

Instalación y Uso

1. Clonar e instalar dependencias

git clone https://github.com/Neem2004/android-mcp-server.git
cd android-mcp-server
npm install

2. Compilar

npm run build

Esto genera el código compilado en la carpeta dist/.

⚠️ Importante: dist/ se genera localmente y no se sube al repositorio. Debes ejecutar npm run build antes de configurar tu cliente MCP, o el servidor no arrancará.

💡 Inicio rápido (publicado en npm): puedes saltarte el clonado y la compilación — el servidor está publicado como @neem2004/android-mcp-server e incluye el dist/ compilado. Ejecútalo directamente con npx -y @neem2004/android-mcp-server, como muestran las configuraciones de abajo. La forma de ruta absoluta apunta a un clon local (reemplaza TU_RUTA por su ubicación).

3. Configurar tu cliente MCP

Cada cliente MCP guarda sus servidores en un archivo distinto, con un formato propio. A continuación están las tres configuraciones más comunes, cada una con la forma de paquete publicado (npx) y la alternativa de clon local.

OpenCode (asistente de IA / CLI)

Archivo: opencode.json en la raíz de tu proyecto, o ~/.config/opencode/opencode.json (global).

{
  "mcp": {
    "android": {
      "type": "local",
      "command": ["npx", "-y", "@neem2004/android-mcp-server"],
      "enabled": true
    }
  }
}

Alternativa de clon local — "command": ["node", "TU_RUTA/android-mcp-server/dist/index.js"].

Claude Desktop (asistente de IA)

Archivo: %APPDATA%\Claude\claude_desktop_config.json (Windows) o ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["-y", "@neem2004/android-mcp-server"]
    }
  }
}

Alternativa de clon local — "command": "node" con "args": ["TU_RUTA/android-mcp-server/dist/index.js"].

VS Code (editor con soporte de Copilot / agente MCP)

Archivo: .vscode/mcp.json en tu workspace (o mediante el comando MCP: Open User Configuration). VS Code usa servers como clave raíz (no mcpServers).

{
  "servers": {
    "android": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@neem2004/android-mcp-server"]
    }
  }
}

Alternativa de clon local — "command": "node" con "args": ["TU_RUTA/android-mcp-server/dist/index.js"].

Nota de desarrollo: en lugar del build compilado puedes ejecutar TypeScript directamente con tsx reemplazando el argumento por src/index.ts y usando npx tsx como comando. Para máxima fiabilidad, prefiere el build compilado.

4. Validación básica

npm test           # ejecuta la suite de tests unitarios
npm run build      # compila TypeScript a dist/
npm run dev        # ejecuta el servidor directamente con tsx (desarrollo)

Tools disponibles

Tool	Descripción	Argumentos
adb_get_logcat	Vuelca el buffer de logcat con filtros opcionales	lines, filter_tag, log_level
adb_clear_logcat	Limpia el buffer de logs del dispositivo	—
adb_dump_hierarchy	Devuelve la jerarquía de la UI actual (XML/texto)	—
adb_list_packages	Lista los paquetes instalados	filter, include_system
adb_execute_shell	Ejecuta un comando shell seguro (lista blanca)	command

Seguridad

Este servidor prioriza la seguridad frente a la ejecución arbitraria de comandos:

• Lista blanca de comandos shell: adb_execute_shell solo acepta comandos cuyo prefijo esté autorizado (getprop, dumpsys, pm list). Cualquier otra cosa se rechaza con un error descriptivo. También se bloquean encadenamientos (&&, ||, ;, |) y metacaracteres de inyección.
• Sin root: no se solicitan privilegios de superusuario; se trabaja sobre las APIs estándar de ADB.
• Los comandos se ejecutan mediante execFile (sin pasar por un shell intermedio), evitando la inyección de metacaracteres.

La lógica vive en src/adb/security.ts; revísalo antes de ampliar los permisos.

Configuración de ADB

Si aún no tienes ADB:

• Windows: descarga los platform-tools oficiales y agrega su carpeta al PATH del sistema.
• macOS / Linux: instala con tu gestor de paquetes (p. ej. brew install android-platform-tools, apt install adb).

Verifica con:

adb devices

Tu dispositivo debe aparecer como device (no unauthorized/offline). El servidor usará ADB_PATH, luego ANDROID_HOME/ANDROID_SDK_ROOT, luego rutas estándar del SDK, antes de caer a adb en el PATH.

Patrocinio

Este proyecto es 100% open source y se mantiene de forma independiente. Si Android ADB MCP Server ahorra tiempo a tu equipo o mejora tus flujos de automatización, considera apoyar su desarrollo continuo.

• 🔗 GitHub Sponsors: Patrocina a Neem2004
• 💼 Empresas: el patrocinio corporativo financia nuevas herramientas, mejoras de seguridad y soporte prioritario.

Toda contribución, por pequeña que sea, ayuda a mantener el proyecto activo, documentado y seguro. ¡Gracias por tu apoyo!

Licencia

ISC