home / mcp / android mcp server

Android MCP Server

MCP Android agent - This project provides an *MCP (Model Context Protocol)* server for automating Android devices using uiautomator2. It's designed to be easily plugged into AI agents like GitHub Copilot Chat, Claude, or Open Interpreter to control Android devices through natural language.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "nim444-mcp-android-server-python": {
      "url": "http://localhost:8080"
    }
  }
}

You can automate and control Android devices through MCP by running a local server that exposes a rich set of tools for device management, app control, screen interactions, UI inspection, and advanced capabilities. This server is designed to be easily integrated with AI agents and MCP clients to perform tasks on real devices via natural language commands.

How to use

You run the server in either stdio mode for direct integration with MCP clients or as a streamable HTTP API for web-based or curl-based interactions. In stdio mode, you connect to the local process from your MCP client; in HTTP mode, you send HTTP requests to control the device and query status.

How to install

Prerequisites you need before installation are Python 3.13 or higher and ADB (Android Debug Bridge) installed and available in your system PATH. Ensure your Android device is connected, USB debugging is enabled, and the device supports uiautomator2.

# 1) Clone the project
git clone https://github.com/nim444/mcp-android
cd mcp-android

# 2) Create and activate a virtual environment using uv
uv venv
source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate

# 3) Install dependencies
uv pip install

Configuration and running modes

The server supports two transport modes. Use stdio mode for AI agent integrations and HTTP mode for web or API use. The default setup runs as an HTTP server, and you can switch modes by editing the main startup configuration.

# For stdio mode (AI agents)
if __name__ == "__main__":
    mcp.run(
        transport="stdio",
        show_banner=False,
    )

# For HTTP mode (Web API)
if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="0.0.0.0",
        port=8080,
    )

Using with an MCP client (stdio mode)

To integrate with an MCP client, configure the client to launch the local server in stdio mode. The following JSON snippet demonstrates adding the Android MCP server configuration to your MCP client settings.

{
  "mcpServers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && uv run python server.py"
      ]
    }
  }
}

Using HTTP API (http mode)

If you prefer an HTTP API, start the server in HTTP mode and then interact via HTTP calls. The server will be available at the base URL you configure (default localhost:8080). Example usage is to check the server root to confirm it’s running.

# Check that the HTTP API is responding
curl http://localhost:8080/

Security and notes

Keep your MCP host reachable only to trusted clients. When exposing the HTTP API, consider network restrictions or authentication for sensitive device automation tasks.

Troubleshooting and tips

If you run into connection or device discovery issues, verify that ADB is installed and that the device is connected and authorized for USB debugging. Ensure the virtual environment is active before starting the server and that the correct transport mode is selected for your client.

Available tools

mcp_health

Check if the MCP server is running properly.

get_device_status

Retrieve complete device status and readiness information.

connect_device

Connect to an Android device and obtain basic information.

get_device_info

Get detailed device information such as serial, resolution, battery, and network status.

check_adb_and_list_devices

Verify ADB availability and list connected devices.

get_installed_apps

List all installed apps with version and package information.

get_current_app

Identify the app currently in the foreground.

start_app

Launch an app by its package name.

stop_app

Terminate an app by its package name.

stop_all_apps

Stop all currently running apps.

clear_app_data

Clear user data and cache for a specified app.

screen_on

Turn the device screen on.

screen_off

Turn the device screen off.

unlock_screen

Unlock the screen, performing swipe if necessary.

wait_for_screen_on

Asynchronously wait for the screen to turn on.

press_key

Simulate hardware key presses like home, back, and menu.

click

Tap on UI elements by text, resourceId, or description.

long_click

Perform a long press on a UI element.

send_text

Enter text into the currently focused field, with optional clearing.

swipe

Swipe from one coordinate to another.

drag

Drag an element to a target location.

get_element_info

Obtain detailed information about UI elements.

wait_for_element

Wait for a specific element to appear.

scroll_to

Scroll to bring a target element into view.

screenshot

Capture a screenshot from the device.

dump_hierarchy

Export the current UI hierarchy as XML.

get_toast

Capture the last toast message shown on screen.

wait_activity

Wait for a specific Android activity to appear.