Android Automation MCP server

Android-MCP is a lightweight bridge that connects AI agents with Android devices. Running as an MCP server, it enables large language models to perform real-world tasks on Android such as app navigation, UI interaction, and automated QA testing without requiring computer vision pipelines or preprogrammed scripts.

Key Features

• Native Android Integration: Interact with UI elements via ADB and the Android Accessibility API to launch apps, tap, swipe, input text, and read view hierarchies
• Bring Your Own LLM: Works with any language model without requiring a fine-tuned computer vision model or OCR pipeline
• Rich Toolset: Pre-built tools for gestures, keystrokes, screen capture, and device state monitoring
• Real-Time Interaction: Typical latency between actions ranges from 2-5 seconds depending on device specifications and load

Requirements

• Python 3.10 or higher
• Android Studio
• Android device or emulator running Android 10+

Installation

Setting Up the Environment

First, clone the repository and install dependencies:

git clone https://github.com/CursorTouch/Android-MCP.git
cd Android-MCP
uv pip install -r pyproject.toml

Configuring ADB

Ensure your Android device is recognized by ADB:

adb devices

Your device should appear as "authorized" in the list. If not, check your device's developer options and USB debugging settings.

Connecting to the MCP Server

Add the following JSON configuration to your client config file (replace the placeholders with your actual paths):

{
  "mcpServers": {
    "android-mcp": {
      "command": "{{PATH_TO_UV}}",
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/Android-MCP",
        "run",
        "main.py",
        "--emulator"
      ]
    }
  }
}

Note: The --emulator flag is used by default. Remove it if you want to connect to a physical device instead.

For Claude Desktop users, save this configuration as claude_desktop_config.json in the %APPDATA%/Claude/ directory.

Finalizing Setup

After configuration, restart Claude Desktop. "Android-MCP" should appear as an integration option.

Using Android-MCP

Android-MCP provides several tools that Claude can use to interact with your Android device:

Available Tools

• State-Tool: Gets the current state of the device, including active apps and UI elements
• Click-Tool: Performs a tap at specified coordinates
• Long-Click-Tool: Performs a long press at specified coordinates
• Type-Tool: Types text at specified coordinates with an option to clear existing text
• Swipe-Tool: Performs a swipe gesture from one location to another
• Drag-Tool: Drags from one point to another
• Press-Tool: Simulates hardware key presses (Back, Volume Up, etc.)
• Wait-Tool: Pauses execution for a specified duration
• Notification-Tool: Accesses notifications visible on the device

Example Usage

When using Claude with Android-MCP integration, you can instruct Claude to perform actions like:

• "Open the Settings app on my phone"
• "Check my new email notifications"
• "Navigate to my photos app and swipe through recent pictures"
• "Fill out a form in my banking app"

Troubleshooting

If you encounter issues with the Android-MCP integration:

• Check the logs for error messages
• Verify your device is properly connected and authorized via ADB
• Ensure you have the correct Python version installed
• Restart the Claude Desktop application

For more detailed troubleshooting information, refer to the MCP documentation.

Security Considerations

Android-MCP can execute arbitrary UI actions on your mobile device. For safety, use it in controlled environments such as emulators or dedicated test devices, especially when running untrusted prompts or agents.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "android-mcp" '{"command":"{{PATH_TO_UV}}","args":["--directory","{{PATH_TO_SRC}}/Android-MCP","run","main.py","--emulator"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "android-mcp": {
            "command": "{{PATH_TO_UV}}",
            "args": [
                "--directory",
                "{{PATH_TO_SRC}}/Android-MCP",
                "run",
                "main.py",
                "--emulator"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "android-mcp": {
            "command": "{{PATH_TO_UV}}",
            "args": [
                "--directory",
                "{{PATH_TO_SRC}}/Android-MCP",
                "run",
                "main.py",
                "--emulator"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect