Neem2004/android-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
2. 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).
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).
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).
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
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.