Android MCP 服务器

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

功能

• 🔧 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

示例输出：

已连接设备列表
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:
    """
    获取设备上安装的所有包。
    返回：
        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的所有非数据操作列表
    """

贡献

欢迎贡献！

致谢

• 使用模型上下文协议（MCP）构建