replicant-mcp
Android MCP server for AI-assisted development. Build, test, emulate, and automate.
Open source Open in the app JSON README (API)
About
Android MCP server for AI-assisted development. Build, test, emulate, and automate.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- thecombatwombat
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.6.7
- Stars
- 16
- Forks
- 4
- Open pull requests
- 6
- Last push
- 2026-07-26T10:20:42Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:32
- Updated
- 2026-08-29 04:01:32
- Origin id
io.github.thecombatwombat/replicant-mcp
README
# replicant-mcp
**Let AI build, test, and debug your Android apps.**
[](https://github.com/thecombatwombat/replicant-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/replicant-mcp)
[](https://nodejs.org/)
[](LICENSE)
[](https://deepwiki.com/thecombatwombat/replicant-mcp)
[](https://glama.ai/mcp/servers/thecombatwombat/replicant-mcp)
replicant-mcp is a [Model Context Protocol](https://modelcontextprotocol.io/) 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)
```bash
node --version # Should be 18+
adb --version # Should show Android Debug Bridge version
emulator -version # Should show Android emulator version
```
<details>
<summary><b>Installing prerequisites (macOS via Homebrew)</b></summary>
If you don't already have these tools, install them with [Homebrew](https://brew.sh/):
**Node.js 18+**
```bash
brew install node
```
**Physical-device only** — just `adb`, sufficient if you never run an emulator:
```bash
brew install --cask android-platform-tools
```
`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:
```bash
# 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"
```
Persist `ANDROID_HOME` and put the SDK binaries on your PATH by appending to `~/.zshrc` (or `~/.bashrc`):
```bash
export ANDROID_HOME="$HOME/Library/Android/sdk"
export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"
```
</details>
### Installation
```bash
npm install -g replicant-mcp
```
After installation, run the built-in diagnostics to verify your environment:
```bash
replicant doctor
```
### Updating
```bash
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):
```json
{
"mcpServers": {
"replicant": {
"command": "npx",
"args": ["-y", "replicant-mcp"]
}
}
}
```
### Claude Code
```bash
claude mcp add replicant -- npx -y replicant-mcp
```
### Cursor
Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
```json
{
"mcpServers": {
"replicant": {
"command": "npx",
"args": ["-y", "replicant-mcp"]
}
}
}
```
### Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"replicant": {
"command": "npx",
"args": ["-y", "replicant-mcp"]
}
}
}
```
### OpenAI Codex CLI
Add to `~/.codex/config.toml`:
```toml
[mcp_servers.replicant]
command = "npx"
args = ["-y", "replicant-mcp"]
```
Or via CLI:
```bash
codex mcp add replicant -- npx -y replicant-mcp
```
> **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
```
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](docs/architecture.md) for details.
---
## More Info
- **Configuration:** Set `REPLICANT_CONFIG` for advanced options. See [docs/configuration.md](docs/configuration.md).
- **Logging:** Set `REPLICANT_LOG_LEVEL` (`error`, `warn`, `info`, `debug`) and `REPLICANT_LOG_FORMAT` (`json` for structured output) to control server logging. Logs are written to stderr.
- **Troubleshooting:** Common issues and solutions in [docs/troubleshooting.md](docs/troubleshooting.md).
- **Tool documentation:** Ask Claude to call `rtfm` with a category like "build", "adb", "emulator", or "ui".
---
## Documentation
| Document | Description |
|----------|-------------|
| [Architecture](docs/architecture.md) | Design overview and progressive disclosure pattern |
| [Configuration](docs/configuration.md) | Config file reference, environment variables, Gradle setup |
| [API Stability](docs/api-stability.md) | Tool API versioning policy and deprecation process |
| [Security Model](docs/security.md) | adb-shell safety model, command denylist, threat boundaries |
| [Support Matrix](docs/support-matrix.md) | Tested OS, Node.js, Android SDK, and emulator versions |
| [Known Limitations](docs/known-limitations.md) | Accessibility gaps, timeouts, single-device focus, and more |
| [Artifacts](docs/artifacts.md) | `.replicant/` directory contents and privacy considerations |
| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
| [Changelog](CHANGELOG.md) | Version history |
| [Security Policy](SECURITY.md) | Vulnerability reporting process |
| [Support / Getting Help](SUPPORT.md) | How to report bugs and ask questions |
| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
---
## Acknowledgments
- Inspired by [xc-mcp](https://github.com/conorluddy/xc-mcp) for iOS
- Built on the [Model Context Protocol](https://modelcontextprotocol.io/)
---
## License
[MIT](LICENSE)
---
**Questions?** [Open an issue](https://github.com/thecombatwombat/replicant-mcp/issues)