Mobile Debug Tools

Build, install, control, and inspect Android and iOS apps from an MCP-compatible client. Mobile Debug Tools connects your client to local device toolchains and provides UI actions, screenshots, logs, state assertions, and optional Android performance capture and runtime debugging.

Android, iOS, and Kotlin Multiplatform projects are supported. Flutter and React Native have not been tested. Platform and device limitations are described in the tool reference.

Use responseMode: "compact" for bounded interaction and journey summaries. Retrieve retained details without replaying input with get_interaction_diagnostics; debug output remains available.

What you can use it for

Mobile Debug Tools gives a coding agent access to a running app, so development can include feedback from the device as well as the source code. For example:

• Build and test a feature. After adding a settings screen, build and install the app, navigate to it, and check that its controls display and behave as expected. See app management and UI interactions and assertions.
• Check a bug fix or regression. Reproduce a sequence such as opening a form, entering text and submitting it, then verify the resulting screen or control state. Repeat the journey after a code change to check the outcome.
• Review the UI on a device. Capture screenshots to inspect layout and visual changes, or inspect the UI hierarchy for exposed labels and control state. See observations.
• Investigate an app failure. Collect logs, screenshots and a debug snapshot around a failing action to understand what happened. Evidence correlation links observations to the action.
• Investigate mobile performance or runtime behaviour. Capture a Perfetto or iOS simulator Instruments trace during a slow flow, or attach the runtime debugger to a debuggable app to inspect breakpoints, call stacks and locals on Android or an iOS simulator.

How it works

Your agent client launches a local MCP server and communicates with it over stdio. The server translates tool calls into operations through Android's ADB or Apple's Xcode tools and idb, then returns device observations and action results to the client. It connects to emulators, simulators and supported physical devices through those toolchains.

The agent plugin bundles the server configuration and usage skill. The same server can also be configured directly in an MCP client or run from a source checkout. See code structure for the implementation's module boundaries.

Start here

Choose how to connect:

1. Agent plugin — Recommended. Installs the server configuration and usage skill together for supported agent clients.
2. Direct MCP configuration. Connect the published server to another MCP-compatible client.
3. Manual setup. Build and run a local source checkout.

Check the requirements for your platform before installing.

Requirements

• Node.js >= 22
• Android SDK (adb) for Android support
• Xcode and its command-line tools on macOS for iOS support
• idb for iOS UI inspection and interaction
• JDK 17+ for optional Android runtime debugging; Xcode’s Swift-enabled LLDB/Python for optional iOS simulator debugging

Agent plugin

The plugin installs the MCP server configuration and the mobile-debug-mcp usage skill together. These are GitHub/local installation routes; they do not require approval from a client's public curated marketplace.

Codex

In a terminal with a current Codex CLI:

codex plugin marketplace add clivejefferies/mobile-debug-tools --ref main
codex plugin add mobile-debug-tools@mobile-debug-tools
codex plugin list

Start a new chat/session and confirm the plugin is enabled and its skill and MCP tools are available. These commands use the repository's marketplace, named mobile-debug-tools, not a public directory listing. See the official packaging instructions.

Claude Code

Run these shell commands (not slash commands inside a chat):

claude plugin marketplace add clivejefferies/mobile-debug-tools --scope user
claude plugin install mobile-debug-tools@mobile-debug-tools --scope user
claude plugin list

Restart the session after installation. In an interactive Claude Code chat, the corresponding commands start with /plugin instead of claude plugin. See Claude Code's installation guide.

Cursor

For local installation, clone this repository and run these commands from its root in a macOS/Linux shell:

git clone https://github.com/clivejefferies/mobile-debug-tools.git
cd mobile-debug-tools
cursor_plugin_dir="$HOME/.cursor/plugins/local/mobile-debug-tools"
if [ -e "$cursor_plugin_dir" ]; then
  echo "Move the existing plugin directory aside before copying the new package."
else
  mkdir -p "$(dirname "$cursor_plugin_dir")"
  cp -R agent-plugin/cursor "$cursor_plugin_dir"
fi

On Windows, copy the contents of agent-plugin/cursor into a new ~/.cursor/plugins/local/mobile-debug-tools folder, including .cursor-plugin. Use this generated Cursor-native package, not the portable parent: Cursor does not expand ${PLUGIN_DATA} in portable mcp.json. Do not symlink to the checkout.

Run Developer: Reload Window, open Customize, and confirm the skill and MCP server are loaded. For Teams/Enterprise distribution, import this repository under Dashboard → Plugins & MCPs → Team Marketplaces; its Cursor catalog selects the native package. Members install from Customize. See Cursor's plugin guide.

Antigravity

Install the Antigravity CLI, then clone this GitHub repository and export its plugin:

git clone https://github.com/clivejefferies/mobile-debug-tools.git
cd mobile-debug-tools
npm run package:antigravity -- "$PWD/antigravity-dist"
agy plugin validate --strict "$PWD/antigravity-dist"
agy plugin install "$PWD/antigravity-dist"
agy plugin list --json

No npm install is needed for the export script. Choose a new output directory; the exporter refuses to overwrite an existing one. Check the installed entry has one skill (mobile-debug-mcp) and one MCP server (mobile-debug-mcp), then start a new session and approve the specific MCP calls you intend to use.

The Antigravity-only export avoids strict-validation warnings from the other clients' compatibility files. It uses mcp_config.json and the same pinned npm server and shared skill. GitHub/local installation does not require the Antigravity Marketplace interest form. See Google's plugin guide.

Each client needs Node.js 22 or newer, npx on its PATH, npm registry access on first launch, and the platform toolchains for your device. After installation, ask the agent to list devices, select an explicit emulator/device, and inspect its screen. An installed component list alone does not prove a working device connection. Disable any separate manual registration of this MCP server in the same client to avoid duplicate tools. If a plugin command is unavailable, update the client; the direct MCP configuration works independently.

MCP configuration

For a standard installation, add this stdio server to your client's MCP settings:

{
  "mcpServers": {
    "mobile-debug": {
      "command": "npx",
      "args": ["--yes", "mobile-debug-mcp"]
    }
  }
}

If your client uses separate fields, choose stdio, set the command to npx, and supply --yes and mobile-debug-mcp as arguments. The examples below add optional path overrides; replace the placeholder paths before using them.

Android setup

Recommended when you want Android only, or when you want to make the Android toolchain explicit.

{
  "mcpServers": {
    "mobile-debug": {
      "command": "npx",
      "args": ["--yes", "mobile-debug-mcp"],
      "env": {
        "ADB_PATH": "/path/to/adb",
        "ANDROID_SDK_ROOT": "/path/to/android/sdk",
        "GRADLE_JAVA_HOME": "/path/to/jdk"
      }
    }
  }
}

For Android-only setups, XCRUN_PATH and IDB_PATH are not required unless you want to pin them explicitly.

iOS setup

Recommended when you want iOS simulator or device support, or when idb lives in a non-standard location.

{
  "mcpServers": {
    "mobile-debug": {
      "command": "npx",
      "args": ["--yes", "mobile-debug-mcp"],
      "env": {
        "XCRUN_PATH": "/usr/bin/xcrun",
        "MCP_IDB_PATH": "/path/to/idb",
        "IDB_PATH": "/path/to/idb"
      }
    }
  }
}

For iOS-only setups, ADB_PATH and ANDROID_SDK_ROOT are not required unless you want to pin them explicitly.

Manual setup

For a local source checkout, follow the development setup to install dependencies and build the server. Then configure your MCP client to launch that build over stdio:

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

Replace the path with your checkout location. Rebuild after source changes.

Environment setup

The server discovers platform tools from standard locations and PATH. Leave path overrides unset for a standard installation. Use them for non-standard locations, multiple toolchains, or a pinned development environment.

Variable	Purpose
ADB_PATH	Path to adb.
ANDROID_SDK_ROOT or ANDROID_HOME	Android SDK root.
XCRUN_PATH	Path to xcrun.
MCP_IDB_PATH or IDB_PATH	Path to idb.
GRADLE_JAVA_HOME or JAVA_HOME	Java home for Gradle-backed operations.

After connecting the client, call get_system_status to check discovery and prerequisites. See environment diagnostics if a toolchain or device is unavailable.

Android debugger errors include bounded, sanitized failure classifications and recovery guidance; see the debugger guide.

Documentation

• Documentation guide — find the guide for your task.
• Tool reference — inputs, responses, examples, and shared principles.
• Contributing — develop the server and run its checks.
• Changelog — release history.

License

Apache-2.0

Launch and interaction results distinguish dispatch from timestamped device readiness evidence. Readiness waits account for observed sleeping/locked device blockers. Unknown or unsupported signals are explicit, and no automatic unlock is performed.