Android MCP 服务器

一个通过 ADB（Android 调试桥）提供对 Android 设备进行程序化控制的 MCP（模型上下文协议）服务器。该服务器暴露了各种 Android 设备管理功能，可以通过 MCP 客户端（如 Claude 桌面 和代码编辑器（例如 Cursor）访问。

功能

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

先决条件

• Python 3.x
• 已安装并配置 ADB（Android 调试桥）
• 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" # 从 'adb devices' 获取的设备标识符

对于自动选择，您可以使用以下任意方法：

device:
  name: null              # 显式 null（推荐）
  # name: ""              # 空字符串  
  # name:                 # 或留空/注释掉

查找设备序列号

要查找您的设备标识符，请运行：

adb devices

示例输出：

List of devices attached
13b22d7f        device
emulator-5554   device

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

使用场景

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

使用

需要一个 MCP 客户端来使用此服务器。Claude 桌面应用程序是一个 MCP 客户端的示例。要使用此服务器与 Claude 桌面：

1. 找到您的 Claude 桌面配置文件：

   • 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:
    """
    获取设备上所有已安装的包。
    返回：
        str: 设备上所有已安装包的列表，以字符串形式返回
    """

def execute_adb_command(command: str) -> str:
    """
    执行 ADB 命令并返回输出。
    参数：
        command (str): 要执行的 ADB 命令
    返回：
        str: ADB 命令的输出
    """

def get_uilayout() -> str:
    """
    检索当前 UI 中可点击元素的信息。
    返回一个格式化字符串，包含每个可点击元素的详细信息，
    包括它们的文本、内容描述、边界和中心坐标。

    返回：
        str: 包含可点击元素及其属性的格式化列表
    """

def get_screenshot() -> Image:
    """
    获取设备的截图并返回。
    返回：
        Image: 截图
    """

def get_package_action_intents(package_name: str) -> list[str]:
    """
    获取包的 Activity Resolver Table 中的所有非数据操作
    参数：
        package_name (str): 要获取操作的包名
    返回：
        list[str]: 包的 Activity Resolver Table 中所有非数据操作的列表
    """

贡献

欢迎贡献！

致谢

• 使用 Model Context Protocol (MCP) 构建