{
  "markdown": "# replicant-mcp\n\n**Let AI build, test, and debug your Android apps.**\n\n[![CI](https://github.com/thecombatwombat/replicant-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/thecombatwombat/replicant-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/replicant-mcp)](https://www.npmjs.com/package/replicant-mcp)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/thecombatwombat/replicant-mcp)\n[![replicant-mcp MCP server](https://glama.ai/mcp/servers/thecombatwombat/replicant-mcp/badges/card.svg)](https://glama.ai/mcp/servers/thecombatwombat/replicant-mcp)\n\nreplicant-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.\n\n---\n\n## Demo\n\n![replicant-mcp demo](demo.gif)\n\n---\n\n## Why replicant-mcp?\n\n| Without replicant-mcp | With replicant-mcp |\n|-----------------------|-------------------|\n| \"Run `./gradlew assembleDebug`, then `adb install`, then `adb shell am start`...\" | \"Build and run the app\" |\n| Copy-paste logcat output, lose context | AI reads filtered logs directly |\n| Screenshot → describe UI → guess coordinates | AI sees accessibility tree, taps elements by text |\n| 5,000 tokens of raw Gradle output | 50-token summary + details on demand |\n\n---\n\n## Features\n\n| Category | Capabilities |\n|----------|-------------|\n| **Build & Test** | Build APKs/bundles, run unit and instrumented tests, list modules/variants/tasks, test regression detection with baseline comparison |\n| **Emulator** | Create, start, stop, wipe emulators; save/load/delete snapshots |\n| **Device Control** | List connected devices, select active device, query device properties |\n| **App Management** | Install, uninstall, launch, stop apps; clear app data |\n| **Log Analysis** | Filter logcat by package, tag, level, time |\n| **UI Automation** | Accessibility-first element finding, spatial proximity search, tap, text input, screenshots |\n| **Diagnostics** | Environment health checks via `replicant doctor`; structured logging with configurable level and format |\n\n---\n\n## Coming Soon\n\n- Custom build commands (project-specific overrides, auto-detect gradlew)\n- Video capture (start/stop recording, duration-based capture)\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js 18+**\n- **Android SDK** with `adb` and `emulator` in your PATH\n- An Android project with `gradlew` (for build tools)\n\n```bash\nnode --version      # Should be 18+\nadb --version       # Should show Android Debug Bridge version\nemulator -version   # Should show Android emulator version\n```\n\n<details>\n<summary><b>Installing prerequisites (macOS via Homebrew)</b></summary>\n\nIf you don't already have these tools, install them with [Homebrew](https://brew.sh/):\n\n**Node.js 18+**\n\n```bash\nbrew install node\n```\n\n**Physical-device only** — just `adb`, sufficient if you never run an emulator:\n\n```bash\nbrew install --cask android-platform-tools\n```\n\n`adb` lands directly on your PATH; no further config needed.\n\n**Full Android SDK** — needed for emulator workflows or building APKs via the `gradle-*` tools. Run the steps in order:\n\n```bash\n# 1. JDK — required by sdkmanager itself, and by the gradle-* tools\nbrew install --cask temurin@17\n\n# 2. cmdline-tools (provides sdkmanager)\nbrew install --cask android-commandlinetools\n\n# 3. Set ANDROID_HOME and create the directory BEFORE running sdkmanager,\n#    otherwise sdkmanager has no install target.\nexport ANDROID_HOME=\"$HOME/Library/Android/sdk\"\nmkdir -p \"$ANDROID_HOME\"\n\n# 4. Accept all SDK licenses first, then install packages.\n#    `sdkmanager --install` aborts on unaccepted per-package licenses\n#    (e.g. the Google APIs system image) if licenses aren't accepted first.\n#    The system-image arch must match your host: `arm64-v8a` for Apple\n#    Silicon (M1/M2/M3), `x86_64` for Intel Macs. Check with `uname -m`.\nyes | sdkmanager --licenses\nsdkmanager --install \"platform-tools\" \"emulator\" \"system-images;android-34;google_apis;arm64-v8a\"\n```\n\nPersist `ANDROID_HOME` and put the SDK binaries on your PATH by appending to `~/.zshrc` (or `~/.bashrc`):\n\n```bash\nexport ANDROID_HOME=\"$HOME/Library/Android/sdk\"\nexport PATH=\"$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH\"\n```\n\n</details>\n\n### Installation\n\n```bash\nnpm install -g replicant-mcp\n```\n\nAfter installation, run the built-in diagnostics to verify your environment:\n\n```bash\nreplicant doctor\n```\n\n### Updating\n\n```bash\nnpm update -g replicant-mcp\n```\n\n---\n\n## Setup\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"replicant\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"replicant-mcp\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add replicant -- npx -y replicant-mcp\n```\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):\n\n```json\n{\n  \"mcpServers\": {\n    \"replicant\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"replicant-mcp\"]\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"replicant\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"replicant-mcp\"]\n    }\n  }\n}\n```\n\n### OpenAI Codex CLI\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.replicant]\ncommand = \"npx\"\nargs = [\"-y\", \"replicant-mcp\"]\n```\n\nOr via CLI:\n\n```bash\ncodex mcp add replicant -- npx -y replicant-mcp\n```\n\n> **Note:** Ensure `adb` and `emulator` are in your PATH, or set `ANDROID_HOME` environment variable. On macOS: `~/Library/Android/sdk`, on Linux: `~/Android/Sdk`.\n\n---\n\n## Example\n\n```\nYou: \"I just changed the checkout flow. Build the app, go through checkout\n      with a test product, and make sure the confirmation screen shows up.\"\n\nClaude: [Builds debug APK, installs on emulator, launches app]\n        [Taps \"Electronics\" category → \"Wireless Headphones\" → \"Add to Cart\"]\n        [Navigates to cart, taps \"Checkout\"]\n        [Fills shipping form, taps \"Place Order\"]\n\n        Confirmation screen is showing:\n        - Order #38291\n        - \"Wireless Headphones\" × 1\n        - Total: $79.99\n        - Estimated delivery: Jan 30\n\n        The flow works. Want me to test the edge cases—empty cart,\n        invalid address, payment failure?\n```\n\n---\n\n## Design\n\nreplicant-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.\n\n---\n\n## More Info\n\n- **Configuration:** Set `REPLICANT_CONFIG` for advanced options. See [docs/configuration.md](docs/configuration.md).\n- **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.\n- **Troubleshooting:** Common issues and solutions in [docs/troubleshooting.md](docs/troubleshooting.md).\n- **Tool documentation:** Ask Claude to call `rtfm` with a category like \"build\", \"adb\", \"emulator\", or \"ui\".\n\n---\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Architecture](docs/architecture.md) | Design overview and progressive disclosure pattern |\n| [Configuration](docs/configuration.md) | Config file reference, environment variables, Gradle setup |\n| [API Stability](docs/api-stability.md) | Tool API versioning policy and deprecation process |\n| [Security Model](docs/security.md) | adb-shell safety model, command denylist, threat boundaries |\n| [Support Matrix](docs/support-matrix.md) | Tested OS, Node.js, Android SDK, and emulator versions |\n| [Known Limitations](docs/known-limitations.md) | Accessibility gaps, timeouts, single-device focus, and more |\n| [Artifacts](docs/artifacts.md) | `.replicant/` directory contents and privacy considerations |\n| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |\n| [Changelog](CHANGELOG.md) | Version history |\n| [Security Policy](SECURITY.md) | Vulnerability reporting process |\n| [Support / Getting Help](SUPPORT.md) | How to report bugs and ask questions |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n---\n\n## Acknowledgments\n\n- Inspired by [xc-mcp](https://github.com/conorluddy/xc-mcp) for iOS\n- Built on the [Model Context Protocol](https://modelcontextprotocol.io/)\n\n---\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n**Questions?** [Open an issue](https://github.com/thecombatwombat/replicant-mcp/issues)\n",
  "bytes": 8996,
  "sha": "dd2fafcd9fc0e16b466f15b032ddc01a1bd6ac26588ebe79fb0df4cf9440ca02",
  "repo_slug": "thecombatwombat/replicant-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_thecombatwombat_replicant_mcp_fd680565/readme"
}