replicant-mcp

replicant-mcp

让 AI 为你构建、测试和调试 Android 应用。

replicant-mcp 是一个 Model Context Protocol 服务，可让 Claude 等 AI 助手与您的 Android 开发环境交互。构建 APK、启动模拟器、安装应用、浏览 UI 并调试崩溃——所有操作都能通过自然对话完成。

演示

为什么选择 replicant-mcp？

功能

即将推出

• 自定义构建命令（项目专属覆盖、自动检测 gradlew）
• 视频采集（开始/停止录制、按时长采集）

快速开始

前置条件

• Node.js 18+
• Android SDK，且 adb 和 emulator 位于 PATH 中
• 一个带有 gradlew 的 Android 项目（用于构建工具）

node --version      # Should be 18+
adb --version       # Should show Android Debug Bridge version
emulator -version   # Should show Android emulator version

brew install node

brew install --cask android-platform-tools

# 1. JDK — required by sdkmanager itself, and by the gradle-* tools
brew install --cask temurin@17

# 2. cmdline-tools (provides sdkmanager)
brew install --cask android-commandlinetools

# 3. Set ANDROID_HOME and create the directory BEFORE running sdkmanager,
#    otherwise sdkmanager has no install target.
export ANDROID_HOME="$HOME/Library/Android/sdk"
mkdir -p "$ANDROID_HOME"

# 4. Accept all SDK licenses first, then install packages.
#    `sdkmanager --install` aborts on unaccepted per-package licenses
#    (e.g. the Google APIs system image) if licenses aren't accepted first.
#    The system-image arch must match your host: `arm64-v8a` for Apple
#    Silicon (M1/M2/M3), `x86_64` for Intel Macs. Check with `uname -m`.
yes | sdkmanager --licenses
sdkmanager --install "platform-tools" "emulator" "system-images;android-34;google_apis;arm64-v8a"

export ANDROID_HOME="$HOME/Library/Android/sdk"
export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"

安装

npm install -g replicant-mcp

安装完成后，运行内置诊断以验证环境：

replicant doctor

更新

npm update -g replicant-mcp

设置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "replicant": {
      "command": "npx",
      "args": ["-y", "replicant-mcp"]
    }
  }
}

Claude Code

claude mcp add replicant -- npx -y replicant-mcp

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

{
  "mcpServers": {
    "replicant": {
      "command": "npx",
      "args": ["-y", "replicant-mcp"]
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "replicant": {
      "command": "npx",
      "args": ["-y", "replicant-mcp"]
    }
  }
}

OpenAI Codex CLI

添加到 ~/.codex/config.toml：

[mcp_servers.replicant]
command = "npx"
args = ["-y", "replicant-mcp"]

或通过 CLI：

codex mcp add replicant -- npx -y replicant-mcp

注意： 确保 adb 和 emulator 位于 PATH 中，或设置 ANDROID_HOME 环境变量。在 macOS 上：~/Library/Android/sdk；在 Linux 上：~/Android/Sdk。

示例

You: "I just changed the checkout flow. Build the app, go through checkout
      with a test product, and make sure the confirmation screen shows up."

Claude: [Builds debug APK, installs on emulator, launches app]
        [Taps "Electronics" category → "Wireless Headphones" → "Add to Cart"]
        [Navigates to cart, taps "Checkout"]
        [Fills shipping form, taps "Place Order"]

        Confirmation screen is showing:
        - Order #38291
        - "Wireless Headphones" × 1
        - Total: $79.99
        - Estimated delivery: Jan 30

        The flow works. Want me to test the edge cases—empty cart,
        invalid address, payment failure?

设计

replicant-mcp 使用渐进式披露（先提供摘要，按需展示详情）来尽量减少 token 用量，并采用无障碍优先的 UI 自动化，相比基于屏幕截图的方式，交互更快、更省成本且更可靠。详见 docs/architecture.md。

更多信息

• 配置： 设置 REPLICANT_CONFIG 以使用高级选项。详见 docs/configuration.md。
• 日志记录： 设置 REPLICANT_LOG_LEVEL（error、warn、info、debug）和 REPLICANT_LOG_FORMAT（将其设为 json 以输出结构化日志）来控制服务日志。日志写入 stderr。
• 故障排查： 常见问题及解决方案见 docs/troubleshooting.md。
• 工具文档： 让 Claude 调用 rtfm，并指定“build”“adb”“emulator”或“ui”等类别。

文档

参与贡献

开发环境设置和指南见 CONTRIBUTING.md。

致谢

• 受 iOS 工具 xc-mcp 启发
• 基于 Model Context Protocol 构建

许可证

MIT

有疑问？ 提交议题