Skip to main content
Glama
thecombatwombat

replicant-mcp

by thecombatwombat
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

replicant-mcp

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

CI Node.js License: MIT

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.

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:

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

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

# Clone the repo git clone https://github.com/thecombatwombat/replicant-mcp.git cd replicant-mcp # Install dependencies npm install # Build npm run build # Verify everything works 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.

Alternative: Claude Code Skill

If you use Claude Code (Anthropic's CLI), you can install replicant as a skill instead of an MCP server. This provides shell script wrappers optimized for Claude Code's workflow.

Option 1: Via Plugin Marketplace (Recommended)

/plugin marketplace add thecombatwombat/replicant-mcp /plugin install replicant-dev@replicant-mcp

Option 2: Manual Installation

# From the replicant-mcp directory npm run install-skill

After installation, restart Claude Code to load the skill. The skill provides the same Android development capabilities through shell scripts rather than MCP tools.

Note: The Claude Code skill is currently compatible with macOS and Linux only. Windows support is planned for a future release.

Which should you choose?

  • MCP Server — Use with Claude Desktop or any MCP-compatible client

  • Claude Code Skill — Use with Claude Code CLI for a shell-native experience

Both approaches provide the same core functionality.

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 (No Screenshots Needed!)

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)

This works by reading the accessibility tree—the same data screen readers use. It's faster, cheaper, and more reliable than screenshot-based approaches.

Tool Reference

replicant-mcp provides 12 tools organized into categories:

Build & Test

Tool

Description

gradle-build

Build APKs and bundles (assembleDebug, assembleRelease, bundle)

gradle-test

Run unit and instrumented tests with filtering

gradle-list

List modules, build variants, and tasks

gradle-get-details

Fetch full logs/errors from cached build results

Emulator

Tool

Description

emulator-device

Create, start, stop emulators; manage snapshots

ADB

Tool

Description

adb-device

List devices, select active device, get properties

adb-app

Install, uninstall, launch, stop apps; clear data

adb-logcat

Read filtered device logs by package/tag/level

adb-shell

Run shell commands (with safety guards)

UI Automation

Tool

Description

ui

Dump accessibility tree, find elements, tap, input text, screenshot

Utilities

Tool

Description

cache

Manage cached outputs (stats, clear, config)

rtfm

On-demand documentation for tools

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.

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

License

MIT

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Tools

View all tools

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/thecombatwombat/replicant-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server