Mobile Debug Tools

A minimal, secure MCP server for AI-assisted mobile development. Build, install, interact and inspect Android/iOS apps from an MCP-compatible client.

Support:

• KMP
• Android
• iOS
• Flutter - not tested
• React native - not tested

Requirements

• Node.js >= 18
• Android SDK (adb) for Android support
• Xcode command-line tools for iOS support
• idb for iOS device support

Environment Setup

The server discovers Android and iOS tools automatically from standard locations by default. Manual environment setup is still supported, but it should be treated as the fallback for non-standard installs, overrides, or reproducible pinned toolchains.

Use explicit paths when:

• you have multiple SDKs installed
• the tools live outside standard locations
• you want deterministic setup across machines
• automatic discovery does not find the expected binary

Leave the variables unset when:

• the tools are already on PATH
• the standard Android and Xcode locations are enough

Common environment variables:

• ADB_PATH: explicit path to adb
• ANDROID_SDK_ROOT or ANDROID_HOME: Android SDK root
• XCRUN_PATH: explicit path to xcrun
• MCP_IDB_PATH or IDB_PATH: explicit path to idb
• GRADLE_JAVA_HOME or JAVA_HOME: Java home for Gradle-backed operations

For normal use, call get_system_status first. It reports the detected host, Android, and iOS toolchain state so the client can decide whether automatic discovery is sufficient or whether explicit overrides are needed.

MCP Configuration

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","server"],
      "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","server"],
      "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.

Codex

Use STDIO

command: npx

args:

• --yes
• mobile-debug-mcp

environment variables:

• ADB_PATH: /path/to/adb
• XCRUN_PATH: /usr/bin/xcrun
• IDB_PATH: /path/to/idb
• MCP_IDB_PATH: /path/to/idb
• ANDROID_SDK_ROOT: /path/to/android/sdk
• GRADLE_JAVA_HOME: /path/to/jdk
• JAVA_HOME: /path/to/jdk

If you are unsure whether the environment is configured correctly, run get_system_status first. It reports the detected host, Android, and iOS toolchain state in a structured form.

Agent Plugin

For clients that support Agent Plugins, the agent-plugin package installs the MCP server configuration together with the existing usage skill. Direct npm/MCP configuration above remains supported.

Codex plugin

Install the plugin from this repository's marketplace:

codex plugin marketplace add clivejefferies/mobile-debug-tools
codex plugin add mobile-debug-tools@mobile-debug-tools

Claude Code plugin

Install the plugin from this repository's marketplace:

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

Cursor plugin

The repository includes a Cursor marketplace. Teams and Enterprise admins can import the repository in Dashboard → Plugins & MCPs → Team Marketplaces. To test it locally, copy agent-plugin into ~/.cursor/plugins/local/mobile-debug-tools, then reload Cursor.

Start a new chat or session after installation so the client loads the skill and MCP tools. Each plugin launches the published npm package locally and needs Node.js 18 or newer and the platform toolchains for your device. If you also registered the MCP server directly, disable that registration to avoid duplicate tools.

Usage

Crash fixing:

I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available

Feature building:

Add a button, hook into the repository and confirm API request successful

Docs

• Tools: Tools — full input/response examples
• Changelog: Changelog
• Agents: AGENTS.md — cold-start guidance for autonomous agents entering the public repo
• Skills: skills/README.md — portable Markdown skill packages for agents such as Copilot, Codex, Claude, or custom systems

License

Apache-2.0