Local Android MCP

A local-only, model-agnostic MCP server and installer that lets GitHub Copilot, Codex, Claude, Cursor, Gemini, Devin/Windsurf, and other MCP clients operate an Android device through ADB.

The server contains no language model and calls no cloud API. The MCP client supplies the reasoning; this package supplies a deliberately constrained Android tool surface.

Requirements

• Node.js 20 or newer

• Android platform-tools (adb)

• An Android device with USB debugging enabled, or an authorized wireless ADB device

Confirm the device before setup:

adb devices -l

The device state must be device, not unauthorized or offline.

Related MCP server: phone-control

Get the source

git clone https://github.com/manuelcabrera1193/droid.git
cd droid
npm ci

The GitHub repository is public. The npm package remains marked private to prevent accidental registry publication; local installation is supported.

One-command multi-client setup

Install a self-contained global copy, detect the AI clients on this computer, review the plan, and apply it:

npm install
npm run install:global
local-android-mcp detect
local-android-mcp setup
local-android-mcp setup --yes --force
local-android-mcp doctor
local-android-mcp ui

setup without --yes is always a read-only plan. The applied setup:

• registers one stable local-android-mcp command, never the source folder;

• configures every detected compatible client;

• merges existing JSON/JSONC instead of replacing it;

• creates timestamped sibling backups before changes;

• uses vendor CLIs for Codex, Claude Code, and Devin;

• refuses malformed configuration and conflicting entries unless --force is explicit.

--force is required for Codex, Claude Code, and Devin because their official CLI may replace an existing same-named entry and does not expose portable installer ownership metadata. Always inspect the plan first.

Limit setup to selected clients when needed:

local-android-mcp setup --client vscode,cursor,codex
local-android-mcp setup --client vscode --yes
local-android-mcp uninstall --client vscode --yes

Uninstalling a provider-CLI-owned entry (codex, claude-code, or devin) requires --force because those formats do not expose portable ownership metadata. Inspect the plan and provider configuration first.

Supported IDs are vscode, copilot, cursor, claude-code, claude-desktop, codex, gemini, devin, and windsurf-legacy. Windows configurations use cmd.exe with the absolute npm shim dynamically resolved during setup, preventing an untrusted workspace from shadowing the command. macOS and Linux use the stable global command directly. Rerun setup after moving to another computer or changing the Windows Node installation.

Local device selector

Run:

local-android-mcp ui

The command starts an ephemeral web server bound only to 127.0.0.1, opens the default browser, and remains active until you press Ctrl+C. From the panel you can select or clear the default device, inspect authorization state, refresh a screenshot, and start a configured Android Virtual Device. The page refreshes its inventory automatically.

The selected card exposes Deseleccionar, which removes the saved preference and returns to automatic selection. If Actualizar cannot reach the local service, keep the terminal that runs local-android-mcp ui open. With a fixed port, restarting local-android-mcp ui --port 3210 lets the same page renew its local session on the next refresh.

The selection is read dynamically by the MCP server, so changing it does not require editing every AI client. Selection precedence is:

1. the device argument supplied by an MCP tool;

2. ANDROID_SERIAL from the MCP client environment;

3. the device saved by the local web panel;

4. automatic selection when exactly one authorized device exists.

Use local-android-mcp ui --no-open on a headless machine, or --port 3210 when a predictable localhost port is useful. The UI exposes no LAN listener, uses a per-process request token, and does not call a cloud service.

See docs/CLIENT-COMPATIBILITY.md for exact destinations and docs/AI-INTEGRATION.md for a guide written for both developers and coding agents.

For a new computer, follow docs/INSTALL-MAC-WINDOWS.md.

Workspace-only setup (GitHub Copilot)

npm install
npm test
npm run smoke
npm run smoke:device

The repository-root .mcp.json is portable. It runs npm in the workspace instead of containing an absolute path, so the whole folder can be moved or copied to another computer. On the other computer, install Node.js and ADB, run npm install, and open the folder in VS Code.

In VS Code:

1. Open this folder as the workspace.

2. Open the Command Palette and run MCP: List Servers.

3. Start or restart local-android if it is not already running.

4. In Copilot Agent mode, ask: List the connected Android devices using local-android.

GitHub Copilot's portable workspace format uses mcpServers; the older .vscode/mcp.json format uses a different top-level key and is intentionally not duplicated here.

Global, source-location-independent installation

To use the server from unrelated workspaces, install a packaged copy:

npm install
npm run install:global

This builds an npm tarball and installs a copy globally. Moving or deleting the source folder afterward does not break the local-android-mcp command. The automatic setup command is recommended; examples/global-mcp.json remains available for manual clients.

Common destinations:

• GitHub Copilot CLI: $COPILOT_HOME/mcp-config.json, or ~/.copilot/mcp-config.json

• Codex: $CODEX_HOME/config.toml, or ~/.codex/config.toml

• Claude Code: $CLAUDE_CONFIG_DIR/.claude.json, or ~/.claude.json

• A compatible workspace: .mcp.json

• Claude Desktop: its mcpServers configuration

Do not overwrite an existing global configuration file; merge only the local-android entry.

Dynamic ADB and device selection

The server resolves ADB in this order:

1. ANDROID_ADB_PATH

2. ADB_PATH

3. ANDROID_SDK_ROOT/platform-tools/adb

4. ANDROID_HOME/platform-tools/adb

5. adb found on PATH

No repository, SDK, home-directory, or device path is hard-coded.

When exactly one authorized device exists, it is selected automatically. With multiple devices, pass device to a tool or set ANDROID_SERIAL before the MCP client starts.

Examples:

export ANDROID_SERIAL=emulator-5554
export ANDROID_ADB_PATH=/custom/android-sdk/platform-tools/adb

These variables are optional. Keep machine-specific values outside committed MCP configuration.

The UI also resolves the Android Emulator through ANDROID_EMULATOR_PATH, EMULATOR_PATH, the active Android SDK, and finally PATH.

Exposed tools

Security boundaries

• Commands use process argument arrays with local shell execution disabled.

• There is no arbitrary adb shell tool.

• Package names, coordinates, durations, keys, and text are validated.

• Text containing shell metacharacters is rejected before reaching the device.

• Commands have timeouts and output-size limits.

• There are no install, uninstall, clear-data, reboot, file-transfer, or root tools.

• MCP runs over local stdio and opens no listening network port.

ADB itself is a privileged debugging interface. Use a dedicated test device and review tool approvals in the MCP client.

Do not commit device screenshots, UI dumps, private design links, device identifiers, credentials, or signing keys. The repository excludes common local artifacts, and CI scans the Git history with Gitleaks. Test fixtures use synthetic device names and documentation-only network addresses.

Development and verification

npm run check         # TypeScript without output
npm test              # Build plus unit tests
npm run smoke         # Start a real MCP client/server session and list devices
npm run smoke:device  # Read device info, screenshot, and UI tree
npm pack --dry-run    # Inspect the portable package contents
local-android-mcp detect --json
local-android-mcp setup --dry-run

The unit tests cover portable ADB discovery, device parsing and selection, argument construction, client detection, JSONC-preserving configuration merges, backup/conflict behavior, package validation, and remote-shell text rejection.

Documentation map

• AGENTS.md: repository rules and implementation map for coding agents.

• llms.txt: compact discovery entrypoint for language models.

• docs/AI-INTEGRATION.md: implementation and project-integration contract.

• docs/CLIENT-COMPATIBILITY.md: supported clients and configuration ownership.

• docs/INSTALL-MAC-WINDOWS.md: portable setup on another macOS or Windows computer.

• docs/local-android.manifest.json: machine-readable capability manifest.