Android MCP Server

Android MCP 服务

一个 MCP（Model Context Protocol）服务，通过 ADB（Android Debug Bridge）以编程方式控制 Android 设备。此服务提供多种 Android 设备管理功能，可供 MCP 客户端使用， 例如 Claude 桌面应用和代码编辑器 （例如 Cursor）

功能

• 🔧 ADB 命令执行
• 📸 设备截图
• 🎯 UI 布局分析
• 📱 设备软件包管理

前提条件

• Python 3.x
• 已安装并配置 ADB（Android Debug Bridge）
• Android 设备或模拟器（未经测试）

安装

1. 克隆仓库：

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

2. 安装依赖： 本项目使用 uv 管理项目， 可通过多种方式 安装。

uv python install 3.11
uv sync

配置

此服务支持灵活的设备配置，可适用于多种使用场景。

设备选择模式

1. 自动选择（推荐用于单台设备）

• 无需配置文件
• 自动连接到唯一已连接的设备
• 非常适合使用单台测试设备进行开发

2. 手动选择设备

• 在连接了多台设备时使用
• 在配置文件中指定确切的设备

配置文件（可选）

配置文件（config.yaml）是可选的。如果该文件不存在，且仅连接了一台设备，服务将自动选择该设备。

自动选择

确保只连接一台设备，然后运行服务即可，无需配置！

手动选择

1. 创建配置文件：

cp config.yaml.example config.yaml

2. 编辑 config.yaml 并指定设备：

device:
  name: "your-device-serial-here" # Device identifier from 'adb devices'

自动选择可使用以下任一方法：

device:
  name: null              # Explicit null (recommended)
  # name: ""              # Empty string  
  # name:                 # Or leave empty/comment out

查找设备序列号

运行以下命令，查找设备标识符：

adb devices

示例输出：

List of devices attached
13b22d7f        device
emulator-5554   device

使用第一列的值（例如 13b22d7f 或 emulator-5554）作为设备名称。

使用场景

场景	是否需要配置	行为
连接了一台设备	无	✅ 自动连接到该设备
连接了多台设备，想使用特定设备	config.yaml 中的 device.name	✅ 连接到指定设备
连接了多台设备，未配置	无	❌ 显示包含可用设备的错误信息
未连接任何设备	不适用	❌ 显示“无设备”错误

注意：如果连接了多台设备，但未指定要使用哪台，服务将显示错误消息并列出所有可用设备。

使用方法

需要使用 MCP 客户端才能使用此服务。Claude Desktop 应用是 MCP 客户端的一个示例。要在 Claude Desktop 中使用此服务：

1. 找到 Claude Desktop 配置文件：

   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json

2. 将 Android MCP 服务配置添加到 mcpServers 部分：

{
  "mcpServers": {
    "android": {
      "command": "path/to/uv",
      "args": ["--directory", "path/to/android-mcp-server", "run", "server.py"]
    }
  }
}

替换：

• 将 path/to/uv 替换为 uv 可执行文件的实际路径
• 将 path/to/android-mcp-server 替换为克隆此仓库的绝对路径

https://github.com/user-attachments/assets/c45bbc17-f698-43e7-85b4-f1b39b8326a8

可用工具

此服务提供以下工具：

def get_packages() -> str:
    """
    Get all installed packages on the device.
    Returns:
        str: A list of all installed packages on the device as a string
    """

def execute_adb_command(command: str) -> str:
    """
    Executes an ADB command and returns the output.
    Args:
        command (str): The ADB command to execute
    Returns:
        str: The output of the ADB command
    """

def get_uilayout() -> str:
    """
    Retrieves information about clickable elements in the current UI.
    Returns a formatted string containing details about each clickable element,
    including their text, content description, bounds, and center coordinates.

    Returns:
        str: A formatted list of clickable elements with their properties
    """

def get_screenshot() -> Image:
    """
    Takes a screenshot of the device and returns it.
    Returns:
        Image: the screenshot
    """

def get_package_action_intents(package_name: str) -> list[str]:
    """
    Get all non-data actions from Activity Resolver Table for a package
    Args:
        package_name (str): The name of the package to get actions for
    Returns:
        list[str]: A list of all non-data actions from the Activity Resolver
        Table for the package
    """

贡献

欢迎贡献！

致谢

• 使用 Model Context Protocol (MCP)构建