Let AI build, test, and debug your Android apps.
replicant-mcp
Let AI build, test, and debug your Android apps.
replicant-mcp is a Model Context Protocol server that gives AI assistants like Claude the ability to interact with your Android development environment. Build APKs, launch emulators, install apps, navigate UIs, and debug crashes—all through natural conversation.
Demo
Why replicant-mcp?
| Without replicant-mcp | With replicant-mcp |
|---|---|
"Run ./gradlew assembleDebug, then adb install, then adb shell am start..." |
"Build and run the app" |
| Copy-paste logcat output, lose context | AI reads filtered logs directly |
| Screenshot → describe UI → guess coordinates | AI sees accessibility tree, taps elements by text |
| 5,000 tokens of raw Gradle output | 50-token summary + details on demand |
Features
| Category | Capabilities |
|---|---|
| Build & Test | Build APKs/bundles, run unit and instrumented tests, list modules/variants/tasks, test regression detection with baseline comparison |
| Emulator | Create, start, stop, wipe emulators; save/load/delete snapshots |
| Device Control | List connected devices, select active device, query device properties |
| App Management | Install, uninstall, launch, stop apps; clear app data |
| Log Analysis | Filter logcat by package, tag, level, time |
| UI Automation | Accessibility-first element finding, spatial proximity search, tap, text input, screenshots |
| Diagnostics | Environment health checks via replicant doctor; structured logging with configurable level and format |
Coming Soon
- Custom build commands (project-specific overrides, auto-detect gradlew)
- Video capture (start/stop recording, duration-based capture)
Quick Start
Prerequisites
- Node.js 18+
- Android SDK with
adbandemulatorin your PATH - An Android project with
gradlew(for build tools)
node --version # Should be 18+
adb --version # Should show Android Debug Bridge version
emulator -version # Should show Android emulator version
Installation
npm install -g replicant-mcp
After installation, run the built-in diagnostics to verify your environment:
replicant doctor
Updating
npm update -g replicant-mcp
Setup
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):
{
"mcpServers": {
"replicant": {
"command": "npx",
"args": ["-y", "replicant-mcp"]
}
}
}
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"replicant": {
"command": "npx",
"args": ["-y", "replicant-mcp"]
}
}
}
OpenAI Codex CLI
Add to ~/.codex/config.toml:
[mcp_servers.replicant]
command = "npx"
args = ["-y", "replicant-mcp"]
Or via CLI:
codex mcp add replicant -- npx -y replicant-mcp
Note: Ensure
adbandemulatorare in your PATH, or setANDROID_HOMEenvironment variable. On macOS:~/Library/Android/sdk, on Linux:~/Android/Sdk.
Example
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?
Design
replicant-mcp uses progressive disclosure (summaries first, details on demand) to minimize token usage, and accessibility-first UI automation for faster, cheaper, more reliable interactions than screenshot-based approaches. See docs/architecture.md for details.
More Info
- Configuration: Set
REPLICANT_CONFIGfor advanced options. See [docs/config
Tools (5)
build_apkBuild APKs or bundles using Gradle tasks.manage_emulatorCreate, start, stop, or wipe Android emulators and manage snapshots.run_adb_commandExecute raw ADB commands or common helpers like install and launch.analyze_logcatFilter and read logcat output by package, tag, or log level.ui_automationPerform UI interactions using accessibility trees, spatial search, and taps.Environment Variables
ANDROID_HOMEPath to the Android SDK (e.g., ~/Library/Android/sdk)REPLICANT_CONFIGAdvanced configuration options for the serverPATHrequiredMust include adb and emulator binariesConfiguration
{"mcpServers": {"replicant": {"command": "npx", "args": ["-y", "replicant-mcp"]}}}