convez.ai
MCP ServerAutomaçãoAvançado
thecombatwombat

Replicant MCP

thecombatwombat/replicant-mcp

IA controla Android: build, testes, UI e logs via MCP

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que permite que IA construa, teste e depure aplicativos Android através de conversação natural. Integra-se com o ecossistema Android (gradle, adb, emulador) para automatizar build, testes, UI automation e análise de logs com otimização de tokens.

Instalação

$npx convez-ai thecombatwombat/replicant-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
20
Forks
4
Acompanhando
0
Saúde
85%
Último commit
há 2 semanas
Versão
v1.6.7
Issues abertas
7
Contribuidores
2

Casos de uso

  • Automatizar builds e testes de APKs via IA
  • Depuração de apps Android com leitura direta de logcat
  • Automação de UI através da árvore de acessibilidade
  • Gerenciamento de emuladores e dispositivos conectados
  • Análise de crashes e detecção de regressões

Veredito

Ferramenta production-ready e bem-arquitetada para desenvolvedores Android que querem automação via IA. Token-optimized e accessibility-first, mas exige ecosystem Android completo (Node 18+, SDK, adb, gradle).

README

A tradução para o português deste README ainda está na fila.

replicant-mcp

Let AI build, test, and debug your Android apps.

CI npm Node.js License: MIT Ask DeepWiki replicant-mcp MCP server

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

replicant-mcp demo


Why replicant-mcp?

Without replicant-mcpWith replicant-mcp
"Run ./gradlew assembleDebug, then adb install, then adb shell am start...""Build and run the app"
Copy-paste logcat output, lose contextAI reads filtered logs directly
Screenshot → describe UI → guess coordinatesAI sees accessibility tree, taps elements by text
5,000 tokens of raw Gradle output50-token summary + details on demand

Features

CategoryCapabilities
Build & TestBuild APKs/bundles, run unit and instrumented tests, list modules/variants/tasks, test regression detection with baseline comparison
EmulatorCreate, start, stop, wipe emulators; save/load/delete snapshots
Device ControlList connected devices, select active device, query device properties
App ManagementInstall, uninstall, launch, stop apps; clear app data
Log AnalysisFilter logcat by package, tag, level, time
UI AutomationAccessibility-first element finding, spatial proximity search, tap, text input, screenshots
DiagnosticsEnvironment 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)
node --version      # Should be 18+
adb --version       # Should show Android Debug Bridge version
emulator -version   # Should show Android emulator version

If you don't already have these tools, install them with Homebrew:

Node.js 18+

brew install node

Physical-device only — just adb, sufficient if you never run an emulator:

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:

# 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):

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

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 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 for details.


More Info

  • Configuration: Set REPLICANT_CONFIG for advanced options. See 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.
  • Tool documentation: Ask Claude to call rtfm with a category like "build", "adb", "emulator", or "ui".

Documentation

DocumentDescription
ArchitectureDesign overview and progressive disclosure pattern
ConfigurationConfig file reference, environment variables, Gradle setup
API StabilityTool API versioning policy and deprecation process
Security Modeladb-shell safety model, command denylist, threat boundaries
Support MatrixTested OS, Node.js, Android SDK, and emulator versions
Known LimitationsAccessibility gaps, timeouts, single-device focus, and more
Artifacts.replicant/ directory contents and privacy considerations
TroubleshootingCommon issues and solutions
ChangelogVersion history
Security PolicyVulnerability reporting process
Support / Getting HelpHow to report bugs and ask questions
ContributingDevelopment setup and guidelines

Contributing

See CONTRIBUTING.md for development setup and guidelines.


Acknowledgments


License

MIT


Questions? Open an issue

Ver o original no GitHub

Bom para

Relacionados