mobile

Mobile MCP is a server that enables language models to control and interrogate Android devices by consuming structured UI dumps rather than raw screenshots. This allows LLMs to understand and interact with mobile UIs through a parsable, machine-friendly representation of the screen state, elements, and actions. The server is designed to work with Android devices or emulators via adb, enabling automated tasks such as navigation, form completion, and operation workflows using context from the UI dump rather than image-based input.

To use the server, start it through your preferred package manager (for example: npx mobile-mcp). Once running, connect your LLM or orchestration tool to the MCP endpoint and send requests that reference the UI dump schema and available actions. The MCP will return structured results that indicate UI elements, possible actions, and the outcomes of commands, enabling the LLM to reason about the current screen state and select the next appropriate interaction step. Since the server relies on structured data rather than pixel-based input, you can build more reliable, architecture-aware automation flows for Android devices.

Note: This server currently targets Android devices. Ensure adb is properly installed and your device or emulator is connected and authorized before issuing commands. Use the provided UI-dump semantics to drive interactions rather than attempting to interpret raw visual content.

Prerequisites:

• Node.js and npm installed on your system
• Android Studio installed with Android SDK Platform-tools (adb) accessible in your PATH
• An Android device or emulator available and connected via adb (adb devices should list the device)

Installation steps:

1. Install Node dependencies (global install recommended for CLI tools):

   • npm install -g mobile-mcp or use npx to run without global install: npx mobile-mcp install

2. Confirm adb is working:

   • adb version
   • adb devices

3. Start the Mobile MCP server:

   • npx mobile-mcp This launches the MCP server and exposes the endpoints that your LLM or client can communicate with.

4. Optional: Integrate into Claude VS Code workflows as shown in the repository:

   • For Claude Desktop: npx mobile-mcp install
   • Or add to your Claude configuration manually as demonstrated in the README snippet.

Note: If you run into permissions issues on macOS/Linux, you may need to grant adb the necessary permissions or add your user to the appropriate groups. Ensure your device is authorized for USB debugging when using a physical device.

Tips and common issues:

• Android only: iOS support is not available yet.
• Ensure adb is on your PATH and the Android SDK platform-tools are up to date.
• USB debugging must be enabled on the device and the host machine must be authorized to communicate with the device.
• If using an emulator, ensure it is started and fully booted before connecting via MCP.
• When configuring clients, prefer using the structured UI dump interface over visual-based inputs for more reliable automation.
• If you update the mobile-mcp package, re-check adb permissions and device connections, as changes may affect compatibility with existing sessions.
• You can configure how the MCP exposes endpoints and how UI dumps are generated via the server's runtime configuration (see the project docs for advanced options).