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?

Android development involves juggling a lot: Gradle builds, emulator management, ADB commands, logcat filtering, UI testing. Each has its own CLI, flags, and quirks.

replicant-mcp wraps all of this into a clean interface that AI can understand and use effectively:

Current Features

Future Roadmap

Quick Start

Prerequisites

You'll need:

• Node.js 18+
• Android SDK with adb and emulator in your PATH
• An Android project with gradlew (for build tools)

Verify your setup:

node --version  # Should be 18+
adb --version   # Should show Android Debug Bridge version
emulator -version  # Should show Android emulator version

Installation

Option 1: npm (recommended)

npm install -g replicant-mcp

Option 2: From source

git clone https://github.com/thecombatwombat/replicant-mcp.git
cd replicant-mcp
npm install
npm run build
npm test

Connect to Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "replicant": {
      "command": "node",
      "args": ["/absolute/path/to/replicant-mcp/dist/index.js"]
    }
  }
}

Restart Claude Desktop. You should see "replicant" in the MCP servers list.

Connect to Claude Code

Add the MCP server with environment variables for Android SDK:

claude mcp add replicant \
  -e ANDROID_HOME=$HOME/Library/Android/sdk \
  -e PATH="$HOME/Library/Android/sdk/platform-tools:$HOME/Library/Android/sdk/emulator:$HOME/Library/Android/sdk/cmdline-tools/latest/bin:$PATH" \
  -- node $(npm root -g)/replicant-mcp/dist/index.js

Note: Adjust ANDROID_HOME if your Android SDK is in a different location. On Linux, it's typically $HOME/Android/Sdk.

Restart Claude Code to load the MCP server.

Reducing Permission Prompts (Optional)

By default, Claude Code asks for permission on each tool call. To auto-approve replicant-mcp tools, add this to your .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__replicant__*"
    ]
  }
}

This is especially useful for agentic workflows where human intervention is limited.

PR Automation (Optional)

This project includes a Claude Code skill for automated PR handling. When invoked, it:

• Creates a branch and PR from your current changes
• Polls for Greptile and human reviews every 2 minutes (max 5 cycles)
• Automatically addresses Greptile feedback
• Merges when a human approves

To use:

/pr-with-review --branch feature/my-feature --title "My PR" --body "Description" --commit-message "feat: add feature"

Or let Claude invoke it automatically when creating PRs.

Output Directory

replicant-mcp stores screenshots in .replicant/screenshots/ within your current working directory. Add this to your .gitignore:

.replicant/

What Can It Do?

Build & Test

You: "Build the debug variant of the app"

Claude: I'll build the debug APK.
        [Calls gradle-build with operation: "assembleDebug"]

        Build successful in 34s
        APK: app/build/outputs/apk/debug/app-debug.apk (12.4 MB)
        2 warnings (use gradle-get-details for full output)

You: "Run the unit tests for the login module"

Claude: Running unit tests for :feature:login...
        [Calls gradle-test with operation: "unitTest", module: ":feature:login"]

        47 tests passed, 2 failed, 0 skipped

        Failed:
        - LoginViewModelTest.testInvalidEmail
        - LoginRepositoryTest.testNetworkError

        Want me to show the failure details?

Emulator Management

You: "Start up a Pixel 7 emulator"

Claude: I'll start the Pixel_7_API_34 emulator.
        [Calls emulator-device with operation: "start", avdName: "Pixel_7_API_34"]

        Emulator started: emulator-5554
        Waiting for boot... ready!

Install & Launch Apps

You: "Install the APK we just built and open the app"

Claude: Installing and launching...
        [Calls adb-app with operation: "install"]
        [Calls adb-app with operation: "launch"]

        App installed and running on emulator-5554

Debug with Logcat

You: "The app crashed. What happened?"

Claude: Let me check the error logs.
        [Calls adb-logcat with level: "error", lines: 50]

        Found the crash:

        java.lang.NullPointerException: Attempt to invoke virtual method
        'void com.example.User.getName()' on a null object reference
            at com.example.ProfileActivity.onCreate(ProfileActivity.kt:47)

        Looks like `user` is null when ProfileActivity starts.
        Want me to look at that file?

UI Automation (Smart Element Finding)

You: "Tap the Login button"

Claude: I'll find and tap the Login button.
        [Calls ui with operation: "find", selector: { text: "Login" }]
        [Calls ui with operation: "tap", elementIndex: 0]

        Tapped "Login" at coordinates (540, 1847)

Spatial proximity search — find elements near other elements:

You: "Tap the edit icon next to John's name"

Claude: [Calls ui with operation: "find", selector: { textContains: "edit", nearestTo: "John" }]
        Found edit button nearest to "John" at (892, 340)

Multi-tier fallback — when accessibility data isn't available:

1. Accessibility tree — fast, reliable, text-based
2. OCR fallback — Tesseract extracts text from screenshot
3. Visual fallback — returns screenshot + metadata for AI vision

Grid-based precision — tap icons without text labels:

Claude: [Calls ui with operation: "tap", gridCell: 5, gridPosition: 3]
        // Taps center of cell 5 in a 24-cell grid overlay

This approach is faster, cheaper, and more reliable than pure screenshot-based automation.

Tool Reference

replicant-mcp provides 12 tools organized into categories:

Build & Test

Emulator

ADB

UI Automation

Utilities

Want details? Ask Claude to call rtfm with a category like "build", "adb", "emulator", or "ui".

Design Philosophy

Progressive Disclosure

Gradle builds can produce thousands of lines of output. Dumping all of that into an AI context is wasteful and confusing.

Instead, replicant-mcp returns summaries with cache IDs:

{
  "buildId": "build-a1b2c3-1705789200",
  "summary": {
    "success": true,
    "duration": "34s",
    "apkSize": "12.4 MB",
    "warnings": 2
  }
}

If the AI needs the full output (e.g., to debug a failure), it can request it:

{ "tool": "gradle-get-details", "id": "build-a1b2c3-1705789200", "detailType": "errors" }

This typically reduces token usage by 90-99%.

Accessibility-First UI

Most AI-driven UI automation uses screenshots: capture the screen, send it to a vision model, get coordinates, click.

replicant-mcp takes a different approach: it reads the accessibility tree—the same structured data that powers screen readers. This is:

• Faster — No image processing
• Cheaper — Text is smaller than images
• More reliable — Elements are identified by text/ID, not pixel coordinates
• Better for apps — Encourages accessible app development

Single Device Focus

Instead of passing deviceId to every command, you select a device once:

{ "tool": "adb-device", "operation": "select", "deviceId": "emulator-5554" }

All subsequent commands target that device automatically. Simple.

Safety Guards

The adb-shell tool blocks dangerous commands like rm -rf /, reboot, and su. You can run shell commands, but not brick your device.

Configuration

replicant-mcp can be configured via a YAML file. Set the REPLICANT_CONFIG environment variable to the path:

export REPLICANT_CONFIG=/path/to/config.yaml

Example config.yaml:

ui:
  # Always use visual mode (skip accessibility) for these packages
  visualModePackages:
    - com.example.legacy.app

  # Auto-include screenshot when find returns no results (default: true)
  autoFallbackScreenshot: true

  # Include base64-encoded screenshot in responses (default: false)
  includeBase64: false

Most users won't need a config file—the defaults work well for typical Android apps.

Development

Project Structure

src/
  index.ts           # Entry point
  server.ts          # MCP server setup
  tools/             # Tool implementations (one file per tool)
  adapters/          # CLI wrappers (adb, emulator, gradle)
  services/          # Core services (cache, device state, process runner)
  parsers/           # Output parsers
  types/             # TypeScript types
docs/rtfm/           # On-demand documentation
tests/               # Unit and integration tests
scripts/             # Utility scripts

Running Tests

# All tests
npm test

# Unit tests only
npm run test:unit

# Integration tests (MCP protocol compliance)
npm run test:integration

# With coverage
npm run test:coverage

# Full validation (build + all tests)
npm run validate

Checking Prerequisites

npm run check-prereqs

This verifies your Android SDK setup and reports what's available.

Troubleshooting

"No device selected"

Run adb-device with operation: "list" to see available devices, then operation: "select" to choose one. If only one device is connected, it's auto-selected.

"Gradle wrapper not found"

Make sure you're in an Android project directory that contains gradlew. The Gradle tools won't work from other locations.

"Command timed out"

Long-running operations (builds, tests) have a 5-minute default timeout. If your builds are slower, you may need to adjust the timeout in the adapter.

Emulator won't start

Check that:

1. You have an AVD created (avdmanager list avd)
2. Virtualization is enabled (KVM on Linux, HAXM on Mac/Windows)
3. Enough disk space for the emulator

Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run npm run validate to ensure tests pass
5. Commit with a descriptive message
6. Push and open a PR

Acknowledgments

• Inspired by xc-mcp for iOS
• Built on the Model Context Protocol
• Thanks to the Android team for adb and the emulator

License

MIT

Questions? Issues? Ideas? Open an issue — we'd love to hear from you.