thecombatwombat/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 adb and emulator in your PATH
- An Android project with gradlew (for build tools)
Installing prerequisites (macOS via Homebrew)
If you don't already have these tools, install them with Homebrew:
**Node.js 18+**
**Physical-device only** — just adb, sufficient if you never run an emulator:
adb lands directly on your PATH; no further config needed.
**Full Android SDK** — needed for emulator workflows or building APKs via the gradle-* tools. Run the steps in order:
Persist ANDROID_HOME and put the SDK binaries on your PATH by appending to ~/.zshrc (or ~/.bashrc):
Installation
After installation, run the built-in diagnostics to verify your environment:
Updating
---
Setup
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
Claude Code
Cursor
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
OpenAI Codex CLI
Add to ~/.codex/config.toml:
Or via CLI:
> **Note:** Ensure adb and emulator are in your PATH, or set ANDROID_HOME environment variable. On macOS: ~/Library/Android/sdk, on Linux: ~/Android/Sdk.
---
Example
---
Design