Home
Servers
Developer Tools
Mcp Android Agent Python

Mcp Android Agent Python

by nim444

386 downloads

Not rated

GitHub

About

This project provides an **MCP (Model Context Protocol)** server for automating Android devices using [uiautomator2](https://github.com/openatx/uiautomator2). It's designed to be easily plugged into AI agents like GitHub Copilot Chat, Claude, or Open Interpreter to control Androi

Details

Author: nim444
Downloads: 386
Categories: Developer Tools, Other, Automation, AI

- Start, stop, and manage apps by package name
- Retrieve installed apps and current foreground app
- Tap, swipe, scroll, drag, and perform UI interactions
- Get device info, screen resolution, and battery status
- Capture screenshots or last toast messages
- Programmatically unlock, wake, or sleep the screen

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Mcp Android Agent Python

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

From the repository

—

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

McpServers

{
    "mcp-android": {
        "type": "stdio",
        "command": "bash",
        "args": [
            "-c",
            "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
        ]
    }
}

Automate Android devices using the uiautomator2 library, requiring adb and a connected device.

This project provides anMCP (Model Context Protocol)server for automating Android devices usinguiautomator2. 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.

The server has been refactored into a clean, modular architecture with tools organized by functionality:

mcp-android-server-python/ ├── server.py # Main server (61 lines - clean & focused) ├── server_original_backup.py # Backup of original monolithic version └── tools/ # 🆕 Modular tools package ├── __init__.py # Central registration & imports ├── device_tools.py # Device connection & status tools ├── app_tools.py # Application management tools ├── screen_tools.py # Screen control & unlock tools ├── input_tools.py # User input simulation (click, swipe, text) ├── inspection_tools.py # UI inspection & screenshots └── advanced_tools.py # Advanced features (toast, activity wait)

- Maintainability: Easy to add/modify/remove tools without touching main server
- Organization: Tools grouped logically by functionality
- Testing: Individual tool modules can be unit tested separately
- Reusability: Tool modules can be reused in other projects
- Scalability: New tool categories can be added as separate modules
- Clean Code: Main server reduced from 1321 lines to 61 lines

- Python 3.13 or higher
- Android Debug Bridge (adb) installed and in PATH
- Connected Android device with USB debugging enabled
- uiautomator2compatible Android device

- Smart Device Detection: Automatically finds and connects to available devices
- Comprehensive Device Info: Get serial, resolution, battery, WiFi IP, Android version
- ADB Diagnostics: Check ADB availability and connection status
- Health Monitoring: Built-in server health checks

- App Discovery: List all installed applications (system + user apps)
- App Lifecycle Control: Start, stop, force-stop apps by package name
- App State Monitoring: Track current foreground app and activity
- Data Management: Clear app data/cache for testing

- Screen Power Management: Turn screen on/off programmatically
- Smart Unlock: Automatic screen unlocking with standard methods
- Screen State Monitoring: Wait for screen activation (async support)

- Precision Interactions: Click by text, resource ID, or content description
- Advanced Gestures: Long click, swipe, drag operations
- Text Input: Smart text entry with optional field clearing
- Hardware Keys: Simulate home, back, menu, volume keys

- Element Analysis: Get detailed UI element properties and bounds
- Screen Capture: Take screenshots for debugging and documentation
- UI Hierarchy: Export complete screen structure as XML
- Smart Waiting: Wait for elements to appear with custom timeouts
- Scroll Detection: Auto-scroll to find elements in long lists

- Toast Detection: Capture system toast messages for verification
- Activity Monitoring: Wait for specific Android activities
- Background Operations: Async support for time-consuming operations

- AI agents that need to interact with real devices
- Remote device control setups
- Automated QA tools
- Android bot frameworks
- UI testing and automation
- Device management and monitoring

git clone https://github.com/nim444/mcp-android.git cd mcp-android

2. Create and activate virtual environment

# Using uv (https://github.com/astral-sh/uv) uv venv source .venv/bin/activate # On Windows: .venv\\Scripts\\activate

The server supports two different transport modes depending on your use case:

Option 1: MCP stdio (For AI Agent Integration)

This is the standard mode for integrating with AI agents like Claude Desktop, VS Code, or other MCP clients.

# Edit server.py to use stdio mode (default commented out) # Uncomment the stdio section and comment out http section # Then run: uv run python server.py

Option 2: Streamable HTTP (For Web/API Integration)

This mode runs the server as an HTTP API, useful for web applications, curl testing, or direct HTTP calls.

# Current default configuration - runs as HTTP server uv run python server.py # Server will be available at: http://localhost:8080

Editserver.pyand modify theif __name__ == "__main__":section:

if __name__ == "__main__": mcp.run( transport="stdio", show_banner=False, )

if __name__ == "__main__": mcp.run( transport="streamable-http", host="0.0.0.0", port=8080, )

For AI Agent Integration (Claude Desktop, VS Code, etc.)

An MCP client is needed to use this server. The Claude Desktop app is an example of an MCP client.

Important:For AI agent integration, make sure to configure the server instdio mode(see "Option 1" above).

Locate your Claude Desktop configuration file

- Windows:%APPDATA%\Claude\claude_desktop_config.json
- macOS:~/Library/Application Support/Claude/claude_desktop_config.json

Add the Android MCP server configuration to the mcpServers section

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

Replace/path/to/mcp-adbwith the absolute path to where you cloned this repository. For example:/Users/username/Projects/mcp-adb

You can also use this MCP server with VS Code's agent mode (requires VS Code 1.99 or newer). To set up:
- Create a.vscode/mcp.jsonfile in your workspace:

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

Replace/path/to/mcp-adbwith the absolute path to where you cloned this repository.

After adding the configuration, you can manage the server using:

- Command Palette →MCP: List Serversto view and manage configured servers
- Command Palette →MCP: Start Serverto start the server
- The server's tools will be available in VS Code's agent mode chat

For HTTP API Integration (Direct API Calls)

When running in HTTP mode (Option 2), you can interact with the server directly via HTTP requests:

# Check if server is running curl http://localhost:8080/ # List available tools (you'll need to implement proper tool discovery endpoints) # This depends on your FastMCP version and configuration

- Web applications with Android automation
- Testing tools that can't use stdio
- Direct API integration with other services
- Debugging and development with curl/Postman

The project includes support for uiauto.dev, a powerful UI inspection tool for viewing and analyzing your device's interface structure.
- Open your browser and navigate tohttps://uiauto.dev

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

AI 測試大師 — MCP server driving pytest / Jest / Cypress / Go / Maestro. Analyze, generate, run, advise. Web + Mobile (iOS/Android/BlueStacks).

AI-powered E2E testing for 10 platforms. 253 MCP tools. Zero config. Test Flutter, React Native, iOS, Android, Web, Electron, Tauri, KMP, .NET MAUI from natural language.

An iOS mobile automation server using Appium and WebDriverAgent, built with clean architecture and SOLID principles.

An iOS mobile automation server using Appium and WebDriverAgent.

A platform-agnostic server for scalable mobile automation and development across iOS, Android, simulators, and emulators.

Automate and control Android devices using the UIAutomator2 framework.

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with web browsers and mobile applications using WebDriverIO. Automate Chrome browsers, iOS apps, and Android apps—all through a unified interface.

MCP server for Mobile Development and Automation | iOS, Android, Simulator, Emulator, and Real Devices

Unified mobile E2E MCP — 28 tools (mobile-mcp + Maestro + RN-debugger parity)

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

{
    "mcpServers": {
        "mcp android agent python": {
            "mcp-android": {
                "type": "stdio",
                "command": "bash",
                "args": [
                    "-c",
                    "cd <DIRECTORY> && source .venv/bin/activate && python -m server"
                ]
            }
        }
    }
}

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

2. Create and activate virtual environment

Option 1: MCP stdio (For AI Agent Integration)

Option 2: Streamable HTTP (For Web/API Integration)

For AI Agent Integration (Claude Desktop, VS Code, etc.)

Locate your Claude Desktop configuration file

Add the Android MCP server configuration to the mcpServers section

For HTTP API Integration (Direct API Calls)

Install

More like this

@mendableai/firecrawl Mcp Server

Umut Naci

Playwright

Sequential Thinking

Sentry

Github