android

Android MCP Server

通过 ADB 控制 Android 模拟器和设备的 MCP 服务。它使 AI 助手能够查看、操作和调试 Android 应用——截取屏幕截图、点击元素、读取日志并记录 Bug。

npm Package | GitHub | Issues

^ 为便于观看，视频已加速。更多演示和测试用例。

功能

• 25 种工具，全面控制 Android 设备
• 截图，支持智能压缩（基于 Sharp，最大 1280px）
• UI 树检查——读取元素层级结构，包括边界、文本、资源 ID 和状态
• 触控自动化——点击、滑动、滚动、输入文本、按下硬件按键
• 元素定位——按 resource-id、文本或 content-desc 查找并点击元素
• 应用生命周期管理——安装 APK、启动应用、查看当前 Activity
• Logcat 集成——按软件包、日志级别或时间戳筛选
• 设备管理——列出设备、启动模拟器、获取设备信息
• 组合操作——tap_and_wait 将点击、等待稳定和 UI 树检查合并为一次往返
• 持久 ADB shell——复用单个 shell 会话，加快命令执行
• 设备信息缓存——每个会话只查询一次设备属性
• 多设备支持——按 ID 指定目标设备
• 无需修改应用——通过 ADB 适用于任何 Android 应用，无需集成 SDK

先决条件

• Node.js 18+
• Android SDK，包含 platform-tools（ADB）和模拟器
• 正在运行的 Android 模拟器或已连接的设备

查找你的 ANDROID_HOME

服务会自动在 ~/Library/Android/sdk（macOS）查找 SDK，或通过 ANDROID_HOME 查找。如果 SDK 位于其他位置，请在 MCP 配置中设置 ANDROID_HOME（见下文）。

检查方法：

# macOS
ls ~/Library/Android/sdk/platform-tools/adb

# Or find it via Android Studio: Settings > Languages & Frameworks > Android SDK

设置

claude mcp add --scope user android -- npx -y android-mcp-server

claude mcp add --scope user --env ANDROID_HOME=/path/to/sdk android -- npx -y android-mcp-server

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["-y", "android-mcp-server"],
      "env": {
        "ANDROID_HOME": "/path/to/android/sdk"
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "android": {
        "command": "npx",
        "args": ["-y", "android-mcp-server"],
        "env": {
          "ANDROID_HOME": "/path/to/android/sdk"
        }
      }
    }
  }
}

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["-y", "android-mcp-server"],
      "env": {
        "ANDROID_HOME": "/path/to/android/sdk"
      }
    }
  }
}

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["-y", "android-mcp-server"],
      "env": {
        "ANDROID_HOME": "/path/to/android/sdk"
      }
    }
  }
}

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["-y", "android-mcp-server"],
      "env": {
        "ANDROID_HOME": "/path/to/android/sdk"
      }
    }
  }
}

git clone https://github.com/martingeidobler/android-mcp-server.git
cd android-mcp-server
npm install
npm run build
claude mcp add --scope user android -- node /path/to/android-mcp-server/dist/index.js

可用工具

设备管理

屏幕截图与 UI 分析

交互

诊断

应用管理

工作流示例

错误记录

“清除日志，打开设置屏幕，点击保存按钮，然后向我展示日志和屏幕截图”

Claude 将执行：clear_logs → launch_app → tap_element → get_logs(package_name="com.example.app", level="E") → screenshot(save_path="./bugs/settings-crash.png")

UI 测试

“浏览登录流程，并确认每个屏幕都与设计稿一致”

Claude 将使用 screenshot + get_ui_tree 查看并理解每个屏幕，使用 tap_element/type_text 进行交互，并利用视觉能力与模型图或描述进行比较。

冒烟测试

“安装 APK，启动应用，并逐一浏览主界面，确认没有崩溃”

Claude 将：install_apk → launch_app → 使用 tap_element 导航 → get_logs(level="E")，在每个界面后检查是否有错误。

元素交互

“打开设置，搜索‘display’，点击第一个结果，然后返回”

Claude 将：launch_app(package_name="com.android.settings") → tap_and_wait(by="text", value="Search settings") → type_text("display") → tap_and_wait(by="text", value="Display") → press_key(key="back")

演示与提示词指南

• DEMOS.md — 可立即尝试的复制粘贴式提示词场景
• PROMPTING.md — 最佳实践、性能技巧和常见陷阱

工作原理

服务通过标准输入/输出使用 Model Context Protocol 进行通信。所有设备交互都通过 ADB 完成，无需修改应用。截图会在内存中捕获并压缩，然后以 base64 图像的形式返回，供 AI 查看和进行视觉分析。

参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

许可证

MIT - 详见 LICENSE。