mcp-android -python

This MCP server provides a Python-based agent to automate Android devices via uiautomator2. It exposes a modular set of tools for device management, application control, screen and input operations, UI inspection, and advanced capabilities like toast detection and activity monitoring. By running under the UV transport, you can connect AI agents or automation clients to the server and issue natural-language or structured commands that map to the underlying tool modules (device_tools, app_tools, screen_tools, input_tools, inspection_tools, and advanced_tools). The server supports two modes: a stdio-like transport for AI agents and an HTTP API mode for web integrations; the configuration here prepares the UV-based runtime for iterative control from compatible MCP clients.

To use, start the server via UV by installing the Python package for the MCP Android server and launching the uv runtime. Then connect from your MCP client (e.g., Claude Desktop, VS Code MCP integration, or other MCP clients) to the mcp-android server. You can leverage the modular tools to discover devices, manage apps, interact with the screen (clicks, swipes, text input), inspect UI elements, capture screenshots, and perform advanced operations like waiting for activities or detecting toasts. The documentation examples in the repository guide how to register the server in your MCP client configuration and how to invoke specific tool functions through the MCP protocol.

Prerequisites:\n- Python 3.13 or higher\n- Android Debug Bridge (adb) installed and in PATH\n- A connected Android device with USB debugging enabled\n- uv (Python package) for running MCP via UV transport\n\nInstallation steps:\n1) Clone the repository:\nbash\ngit clone https://github.com/nim444/mcp-android.git\ncd mcp-android\n\n2) Create and activate a Python virtual environment (recommended):\nbash\npython3.13 -m venv .venv\nsource .venv/bin/activate # Unix/macOS\n# On Windows: .venv\\Scripts\\activate\n\n3) Install dependencies (via uv/uvx workflow as described in the project):\nbash\nuv pip install . # or install your package dependencies as per uv usage\n\n4) Install the MCP Android server package (as used by UV runtime):\nbash\nuv install mcp-android-server-python # package name aligned with repo slug\n\n5) Run the server using UV transport (as in the project examples):\nbash\nuv run python server.py\n

Tips and considerations:\n- Ensure adb is accessible on the host and the Android device is authorized for debugging.\n- The server supports multiple tool modules; you can extend or customize them by editing the tools directory.\n- For AI agents, prefer stdio mode as described in the documentation to enable natural language commands to be mapped to tool actions.\n- If you change the server configuration, you may need to restart the UV transport to pick up the new settings.\n- Regularly update uiautomator2 and adb tooling to maintain compatibility with newer Android versions.\n- When troubleshooting, verify device connectivity with adb devices and check the server health endpoints if using the HTTP mode.\n- The provided architecture emphasizes modularity, so you can add new tool modules without touching the core server logic.