android-adb

The Android ADB MCP Server enables your AI assistant to interact with connected Android devices via ADB commands. It exposes a set of tools that let you list devices, execute shell commands, install or uninstall apps, transfer files, launch apps, and capture screenshots from one or more Android devices. When multiple devices are connected, you can specify a device_id to target a specific device; if only one device is present, the server will use it automatically. The server is designed to integrate with MCP-enabled assistants, letting you perform common Android automation tasks directly from your AI workflow.

To use the server, add it to your MCP configuration (as shown in the Quick Setup) and restart your assistant. Then call the available tools via the MCP interface. The tools include adb_devices (list devices), adb_shell (run shell commands), adb_install/adb_uninstall (manage APKs), adb_list_packages (inspect apps), adb_pull/adb_push (transfer files), launch_app (start apps), and take_screenshot_* (capture images). For device management, remember to provide device_id when multiple devices are connected. Screenshots can be saved to a path you specify or copied to the clipboard, depending on the tool you invoke.

Prerequisites

• ADB must be installed and available in your system PATH. Verify with: adb version
• Node.js 16.x or higher
• Optional: clipboard utilities for screenshots (depends on platform)

Installation steps

1. Install Node.js (if not already installed)

   • Visit https://nodejs.org and install the LTS version for your OS.

2. Install the MCP server package (via npm or npx as shown in Quick Setup)

   • You can install the MCP server by referencing its npm package through npx as in the Quick Setup, or install the package globally if you prefer:

   Quick setup (recommended):

   # In your MCP configuration, use:
   # "command": "npx", "args": ["-y", "@landicefu/android-adb-mcp-server"]
   

   Optional local install for development:

   npm install @landicefu/android-adb-mcp-server
   # If you want to build or run from source, follow the repository's build steps
   

3. When running locally, verify the server starts and is accessible via MCP

   • Ensure your mcp_config points to the correct package name (see Quick Setup)
   • Restart your MCP-enabled assistant to pick up the new server

4. (If you choose to run from source) Build steps (if applicable)

   git clone https://github.com/landicefu/android-adb-mcp-server.git
   cd android-adb-mcp-server
   npm install
   npm run build  # if the project provides a build step
   

Notes

• If using the npx approach, the server will be downloaded and run on demand.
• Ensure ADB is accessible from your shell where the MCP runs.

Tips and troubleshooting:

• ADB not found: Ensure ADB is installed and in PATH. Confirm with adb version.
• No devices detected: Connect an Android device with USB debugging enabled and run adb devices to confirm. On some systems, you may need to authorize the PC on the device.
• Multiple devices: When more than one device is connected, specify device_id in tool calls to target a specific device.
• Permissions: Ensure the account running the MCP server has permission to access adb and the target device files you may pull or push.
• Screenshots: If clipboard-based screenshot tools aren’t working, install the platform-specific utilities (e.g., xclip on Linux, and ensure clipboard access is allowed).
• Network/firewall: If running in a restricted environment, ensure the MCP host can reach any required services (ADB over USB typically bypasses network constraints, but if you’re using wireless ADB, ensure ports are open).

Environment variables (examples):

• ADB_PATH: optional override for the adb executable if not in PATH
• NPM_CONFIG_PREFIX: if you install npm packages globally and need a custom prefix