Android ADB MCP Server

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

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