Android ADB MCP Server is a Model Context Protocol (MCP) server that allows AI assistants to securely control Android devices via ADB. It is aimed at developers and automation scenarios that need to let AI assistants directly operate or read the state of Android devices.
Purpose
Let MCP-capable AI assistants (such as Claude, OpenCode, and VS Code using MCP through Copilot/agent integration) interact with Android devices via ADB. Note that Claude and OpenCode are AI assistants, while VS Code itself is not an AI, but a code editor that hosts AI assistants and acts as an MCP client; this server can work with any client that supports MCP.
Main capabilities
The server exposes the following tools: reading logcat, inspecting the current UI hierarchy, listing installed packages, and executing restricted shell commands. All commands are constrained by an allowlist to reduce the risk of arbitrary command execution.
Security design
- Shell allowlist: adb_execute_shell only accepts commands with authorized prefixes (getprop, dumpsys, pm list). Other commands are rejected with a descriptive error. Command chains (&&, ||, ;, |) and metacharacters used for injection are also blocked.
- No root: does not request superuser privileges, and uses only standard ADB APIs.
- Commands are executed via execFile (without going through an intermediate shell), avoiding metacharacter injection.
- The security logic is located in src/adb/security.ts and should be reviewed before expanding permissions.
Prerequisites
- Node.js v18+ (tested up to Node.js 26).
- ADB is installed and accessible via the system PATH (adb version must be available), or located via ADB_PATH / ANDROID_HOME / standard SDK paths.
- The Android device has USB debugging enabled (Developer options → USB debugging).
Installation and usage
The build generates compiled code in the dist/ folder. Note: dist/ is generated locally and is not committed to the repository, so npm run build must be run before configuringthe MCP client, otherwise the server cannot start.
Quick start (published to npm): you can skip cloning and building; the server has been published as @neem2004/android-mcp-server and includes the compiled dist/. Run npx -y @neem2004/android-mcp-server directly. The absolute path form is suitable for local clones (replace YOUR_PATH_TO with the actual location).
The configuration files and formats differ for each MCP client. Common configurations are as follows:
- OpenCode: the file is opencode.json in the project root, or the global ~/.config/opencode/opencode.json. Local clone alternative: "command": ["node", "YOUR_PATH_TO/android-mcp-server/dist/index.js"].
- Claude: the file is %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS). Local clone alternative: "command": "node", "args": ["YOUR_PATH_TO/android-mcp-server/dist/index.js"].
- VS Code: the file is .vscode/mcp.json in the workspace (or via the MCP: Open User Configuration command). VS Code uses servers as the top-level key (not mcpServers).
Development tip: you can use tsx to run TypeScript directly, replacing the argument with src/index.ts and using npx tsx as the command; however, for reliability, it is recommended to use the compiled build.
ADB configuration
If ADB is not yet installed:
- Windows: download the official platform-tools and add its folder to the system PATH.
- macOS / Linux: install via a package manager (for example, brew install android-platform-tools, apt install adb). The device should appear as device (not unauthorized / offline). The server will use ADB_PATH, ANDROID_HOME / ANDROID_SDK_ROOT, the standard SDK path in turn, and finally fall back to adb in PATH.
Project and Support
This project is 100% open source and independently maintained. If it helps your team's automation workflows, you can support Neem2004 via GitHub Sponsors; corporate sponsorships are used to fund new tools, security hardening, and priority support.
