ADB MCP Server

MCP server for controlling Android, Fire TV, and Android TV devices through ADB.

The intended setup is a local machine in the office, for example a Mac Mini with Android emulators or physical Fire TV devices. A remote agent can start an AVD, inspect and control the selected device, install and uninstall applications, capture optimized screenshots, record evidence through OBS, and collect logcat context around failures.

Installation

This server uses the MCP stdio transport. Build it once, then configure each MCP client to start dist/index.js with Node.js.

Prerequisites:

• Node.js 18.17 or newer.

• ADB installed and able to see the intended devices.

• Android Emulator installed when using list_avds or start_emulator.

• OBS Studio 28 or newer when using the OBS recording tools.

Prepare the server:

git clone <repo-url> adb-mcp-server
cd adb-mcp-server
npm install
npm run build

Find the absolute paths you will need in desktop apps:

pwd
which node
which adb

Use absolute paths for desktop clients. On macOS, GUI apps often do not inherit your shell PATH, so node, adb, the Android Emulator, or OBS may not be found unless you configure explicit paths.

OpenAI Codex CLI, IDE extension, and ChatGPT desktop app

Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share Codex MCP configuration through config.toml. You can add the server with the CLI:

codex mcp add adb \
  --env ADB_EXECUTABLE=/absolute/path/to/adb \
  -- /absolute/path/to/node /absolute/path/to/adb-mcp-server/dist/index.js

Then verify it:

codex mcp list

For explicit configuration, edit ~/.codex/config.toml or a trusted project-scoped .codex/config.toml:

[mcp_servers.adb]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/adb-mcp-server/dist/index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 300

[mcp_servers.adb.env]
ADB_EXECUTABLE = "/absolute/path/to/adb"
ADB_PROJECT_ROOT = "/absolute/path/to/android-project"
ADB_APK_ROOT = "/absolute/path/to/android-project"
ANDROID_EMULATOR_EXECUTABLE = "/absolute/path/to/emulator"
ADB_ALLOWED_AVDS = "Television_1080p_API_34"

Optional OBS variables can be added to the same env table:

# Add these under [mcp_servers.adb.env] when OBS recording is needed.
OBS_EXECUTABLE = "/Applications/OBS.app"
OBS_WEBSOCKET_URL = "ws://127.0.0.1:4455"
OBS_WEBSOCKET_PASSWORD = "replace-with-the-local-password"
OBS_EMULATOR_SCENE = "Android Emulator"
OBS_EMULATOR_SOURCE = "Android Emulator Capture"
OBS_PHYSICAL_DEVICE_SCENE = "Physical Device - HDMI"
OBS_PHYSICAL_DEVICE_SOURCE = "Capture Card"

In the Codex TUI, use /mcp to inspect connected servers. In the Codex IDE extension or ChatGPT desktop app, open settings, add an MCP server, choose STDIO, and use the same command, args, and environment values shown above.

ChatGPT web does not read local Codex MCP configuration. To use this local stdio server with OpenAI clients, use Codex CLI, the IDE extension, or the ChatGPT desktop app on the machine that has ADB access.

Usage skills

This repository includes a Codex/OpenAI skill template at .agents/skills/adb-mcp-server. The MCP server can be configured globally, but the skill should be installed in the app repository where the agent is doing the Android work.

For OpenAI Codex, Codex IDE extension, and ChatGPT desktop app, install it as a repo-local skill under .agents/skills:

mkdir -p /absolute/path/to/android-project/.agents/skills
cp -R .agents/skills/adb-mcp-server /absolute/path/to/android-project/.agents/skills/

Then commit it in the target repository so the team gets the same workflow:

cd /absolute/path/to/android-project
git add .agents/skills/adb-mcp-server
git commit -m "docs: add ADB MCP usage skill"

For a personal Codex/OpenAI skill available across all repositories, copy the same folder to ~/.agents/skills/adb-mcp-server instead:

mkdir -p ~/.agents/skills
cp -R .agents/skills/adb-mcp-server ~/.agents/skills/

For Claude Code, install the same instructions as a Claude project skill under .claude/skills:

mkdir -p /absolute/path/to/android-project/.claude/skills/adb-mcp-server
cp .agents/skills/adb-mcp-server/SKILL.md /absolute/path/to/android-project/.claude/skills/adb-mcp-server/SKILL.md

Then commit it in the target repository:

cd /absolute/path/to/android-project
git add .claude/skills/adb-mcp-server/SKILL.md
git commit -m "docs: add ADB MCP Claude skill"

For a personal Claude Code skill available across all repositories, copy it to ~/.claude/skills/adb-mcp-server/SKILL.md instead:

mkdir -p ~/.claude/skills/adb-mcp-server
cp .agents/skills/adb-mcp-server/SKILL.md ~/.claude/skills/adb-mcp-server/SKILL.md

Claude Code

Claude Code can install this server as a local stdio MCP server:

claude mcp add --scope user --transport stdio \
  --env ADB_EXECUTABLE=/absolute/path/to/adb \
  --env ADB_PROJECT_ROOT=/absolute/path/to/android-project \
  --env ADB_APK_ROOT=/absolute/path/to/android-project \
  adb \
  -- /absolute/path/to/node /absolute/path/to/adb-mcp-server/dist/index.js

Use --scope user to make it available in all your Claude Code projects. Use --scope local for only the current project, or --scope project to create a shared .mcp.json in the repository.

Manage and verify the server:

claude mcp list
claude mcp get adb

Inside Claude Code, use /mcp to inspect server status and approve or authenticate servers when needed.

Project-scoped Claude Code configuration can also be committed as .mcp.json, but avoid hard-coding machine-specific absolute paths in shared repositories unless every developer uses the same layout:

{
  "mcpServers": {
    "adb": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/adb-mcp-server/dist/index.js"],
      "env": {
        "ADB_EXECUTABLE": "/absolute/path/to/adb",
        "ADB_PROJECT_ROOT": "/absolute/path/to/android-project",
        "ADB_APK_ROOT": "/absolute/path/to/android-project"
      },
      "timeout": 300000
    }
  }
}

Claude Desktop

Claude Desktop supports local MCP servers through desktop extensions and through manual JSON configuration. This repository does not currently ship a .mcpb desktop extension, so use manual configuration.

Open Claude Desktop settings, go to the Developer section, and edit claude_desktop_config.json. Common locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this server:

{
  "mcpServers": {
    "adb": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/adb-mcp-server/dist/index.js"],
      "env": {
        "ADB_EXECUTABLE": "/absolute/path/to/adb",
        "ADB_PROJECT_ROOT": "/absolute/path/to/android-project",
        "ADB_APK_ROOT": "/absolute/path/to/android-project",
        "ANDROID_EMULATOR_EXECUTABLE": "/absolute/path/to/emulator"
      }
    }
  }
}

Restart Claude Desktop after saving the file. In a conversation, open the connectors/tools menu and confirm the adb server is connected.

Related MCP server: @wilsonbeam/openclaw-adb-mcp

Tools

• list_devices: list ADB-visible devices, detected platform, and Android shell utility capabilities.

• list_avds: list configured Android Virtual Devices and their running state.

• start_emulator: start an AVD with quick or cold boot and select it as the active device.

• connect_device / disconnect_device: manage ADB-over-TCP targets.

• select_device / clear_active_device: set session device context.

• set_project_root: set the user-confirmed repository root for this MCP session.

• get_device_info: read device model, Android version, screen size, density, and build info.

• screenshot: capture and optimize a PNG screenshot for agent analysis.

• dump_ui: return UI Automator XML when supported by the target.

• wait_for_ui_node: wait until UI Automator XML contains a node matching exact text, resource ID, content description, and/or focus state.

• assert_ui_node: assert that the current UI Automator XML does or does not contain a matching node.

• get_current_activity: inspect the current resumed activity.

• press_key: send safe remote-control key events, including D-pad.

• press_key_sequence: send a bounded timed sequence of safe key events.

• tap, swipe, type_text: perform bounded input operations.

• install_apk: install an APK from the configured APK root.

• uninstall_app: uninstall an application by package name, optionally retaining its data.

• launch_app, stop_app: control an installed application.

• get_logcat: read recent logcat lines with optional text filtering.

• get_obs_status: inspect the active OBS scene and recording state.

• open_obs: open OBS and optionally select a configured capture scene.

• start_obs_recording: verify the configured emulator or physical-device source and start recording.

• stop_obs_recording: stop recording and return the saved video path.

• list_build_profiles: show configured build profiles.

• run_build: run a configured build profile and optionally install the resulting APK.

Vega and Kepler devices

The server detects device capabilities before running Android-specific tools. Ready devices are classified as android, vega, or unknown, and list_devices reports whether the target exposes dumpsys, uiautomator, logcat, input, and screencap.

When a Vega/Kepler device is detected, the server uses the Vega CLI backend where Amazon documents an equivalent:

• press_key, press_key_sequence, tap, swipe, and type_text use inputd-cli through vega exec vda -s <serial> shell.

• get_logcat uses loggingctl log through the Vega device shell.

• launch_app uses vega device launch-app --device <serial> --appName <package>.main.

• screenshot uses gwsi-tool-screenshooter through VDA and then pulls the PNG for optimization. If that device-side backend fails on a Vega Virtual Device, the server falls back to the configured OBS emulator source.

wait_for_ui_node, assert_ui_node, and dump_ui require Android uiautomator. On Vega/Kepler targets that do not expose that Android utility, these tools return a structured unsupported response.

Amazon's Vega documentation states that gwsi-tool-screenshooter works on physical Vega/Kepler devices and does not work on Vega Virtual Device. For virtual-device screenshots, configure OBS_EMULATOR_SCENE and OBS_EMULATOR_SOURCE as a reusable OBS window-capture source. The MCP will try to select the window dynamically from the active device serial/model/product/device before requesting the frame. On unsupported targets, and whenever a required Android shell utility is unavailable, the MCP tool returns a structured unsupported response instead of surfacing raw /bin/sh: command not found output:

{
  "ok": false,
  "reason": "unsupported",
  "message": "dump_ui requires uiautomator, which is not available on this Vega/Kepler device.",
  "device_serial": "emulator-5554",
  "platform": "vega",
  "missing_capability": "uiautomator"
}

Android emulators

list_avds calls the Android Emulator executable to list the available AVDs and correlates them with ADB devices. Running entries include their emulator-XXXX serial and current ADB state.

start_emulator starts an AVD and waits until sys.boot_completed reports that Android is ready. The resulting emulator is selected as the active device for the MCP session:

{
  "avd_name": "Television_1080p_API_34",
  "boot_mode": "cold",
  "headless": false,
  "timeout_ms": 180000
}

• boot_mode: "quick" allows the emulator to restore a Quick Boot snapshot.

• boot_mode: "cold" uses -no-snapshot-load and performs a full boot without loading a snapshot. State may still be saved when the emulator exits.

• headless: true adds -no-window. Do not use it when OBS must capture the emulator window.

The operation is idempotent. If the requested AVD is already running, the existing serial is selected and a second instance is not started. In that case a requested cold boot is not performed.

Use ADB_ALLOWED_AVDS in shared environments to restrict which AVD names an agent may start.

UI waits and assertions

Use wait_for_ui_node and assert_ui_node to verify Android UI state from the UI Automator hierarchy instead of relying on screenshots or OCR. Matching is exact for text, resource_id, and content_desc; focused matches a boolean focus state. At least one of those filters is required.

wait_for_ui_node polls until a match appears or the timeout expires:

{
  "device_serial": "emulator-5554",
  "text": "All The Channels",
  "timeout_ms": 3000,
  "poll_interval_ms": 150
}

When a match is found, the response includes a summarized node:

{
  "found": true,
  "elapsed_ms": 420,
  "node": {
    "text": "All The Channels",
    "resource_id": "rail-title",
    "content_desc": "",
    "class": "android.widget.TextView",
    "focused": false,
    "bounds": "[100,210][1920,250]"
  }
}

If no node matches before the timeout, the response is non-error JSON with found: false.

assert_ui_node checks the current hierarchy once and returns an MCP error when the assertion fails:

{
  "device_serial": "emulator-5554",
  "content_desc": "Home",
  "focused": true
}

To assert absence, set should_exist to false:

{
  "device_serial": "emulator-5554",
  "text": "Search page",
  "should_exist": false
}

Typical TV navigation flow:

{
  "sequence": [
    { "key": "BACK", "delay_ms_after": 1000 },
    { "key": "BACK" }
  ]
}

Then verify the result:

{
  "text": "All The Channels",
  "timeout_ms": 3000
}

Screenshot optimization

The screenshot tool captures a raw PNG with adb exec-out screencap -p on Android devices, or the Vega screenshot backend on supported physical Vega/Kepler devices, then processes it before returning it to the agent. By default it:

• Fits the image inside 1280x720 without enlarging smaller screenshots.

• Uses an indexed PNG palette with up to 256 colours.

• Applies adaptive filtering and maximum PNG compression.

• Reduces the colour palette and then the resolution progressively if needed.

• Enforces a final binary PNG limit of 1048576 bytes (1 MiB).

• Removes incidental metadata during re-encoding.

The tool response reports the original and delivered dimensions and byte sizes. The Base64 representation used by MCP is approximately 33% larger than the binary PNG; ADB_SCREENSHOT_OUTPUT_MAX_BYTES controls the decoded PNG size, not the complete JSON payload.

The raw ADB capture limit and final optimized-image limit are intentionally separate. A large source PNG can be accepted and then compressed instead of failing before processing.

OBS evidence recording

OBS control uses the WebSocket interface built into OBS Studio 28 and later. Before using the recording tools:

1. Open OBS and enable its WebSocket server under Tools → WebSocket Server Settings.

2. Keep authentication enabled and provide the password through OBS_WEBSOCKET_PASSWORD.

3. On macOS, grant OBS the Screen & System Audio Recording permission.

4. Create the scenes and sources that represent the emulator and/or physical device.

5. Configure the exact scene and source names in the MCP server environment.

Example configuration:

OBS_WEBSOCKET_URL=ws://127.0.0.1:4455
OBS_WEBSOCKET_PASSWORD=replace-with-the-local-password
OBS_EMULATOR_SCENE="Android Emulator"
OBS_EMULATOR_SOURCE="Android Emulator Capture"
OBS_PHYSICAL_DEVICE_SCENE="Physical Device - HDMI"
OBS_PHYSICAL_DEVICE_SOURCE="Capture Card"

The server does not expose the WebSocket password to agents. Keep the WebSocket listener bound to localhost unless remote OBS control is explicitly required and secured separately.

Emulator source

Create a macOS Screen Capture source in the configured emulator scene. Application Capture is convenient when only one emulator runs at a time. Window Capture is preferable when multiple AVDs may be open.

When avd_name is supplied, start_obs_recording reads the source's available window and application property values and selects the item containing that AVD name. It then activates the configured scene, confirms that the source is active, and requests a preview image from OBS before starting the recording. If the expected source or AVD window cannot be confirmed, the tool fails without recording another window.

The scene and source must be created once in OBS; the MCP server selects and updates them but does not create platform-specific capture sources from scratch.

{
  "target": "emulator",
  "avd_name": "Television_1080p_API_34",
  "launch_if_needed": true,
  "timeout_ms": 30000
}

Physical-device source

For a physical Android or Fire TV device, configure one of these as the source in the physical-device scene:

• A USB HDMI capture device exposed to OBS as a Video Capture Device.

• A mirroring application such as scrcpy, captured as a window.

ADB itself is not an OBS video source. Protected DRM/HDCP content may appear black and this server does not attempt to bypass content protection.

{
  "target": "physical_device",
  "launch_if_needed": true
}

open_obs starts OBS when necessary and waits for WebSocket to become ready. start_obs_recording is idempotent when OBS is already recording the configured scene; it refuses to switch scenes during a different active recording. stop_obs_recording finalizes the recording and returns the path reported by OBS.

The screenshot tool can also use the configured OBS_EMULATOR_SCENE / OBS_EMULATOR_SOURCE as a host-side fallback for Vega Virtual Device screenshots. This requests a single PNG frame through OBS WebSocket and does not start recording. The source should be a reusable window/application capture input; the MCP attempts to point it at the active emulator window using the selected device serial and ADB details.

Installing and uninstalling applications

set_project_root sets the user-confirmed repository root for the active MCP session. After it is set, install_apk only accepts APK paths contained inside that directory:

{
  "project_path": "/absolute/path/to/MyAndroidTvApp"
}

Use this when the agent is working in a different app repository from the MCP server's configured default root.

install_apk installs an APK located inside the active session project root, or inside the configured ADB_APK_ROOT when no session project root is set. It supports replacing an existing application, installing test-only APKs, and granting runtime permissions:

{
  "apk_path": "artifacts/app-debug.apk",
  "replace": true,
  "allow_test": true,
  "grant_permissions": false,
  "device_serial": "192.168.1.50:5555"
}

uninstall_app removes an installed application using its Android package name:

{
  "package_name": "com.example.tv",
  "keep_data": false,
  "device_serial": "192.168.1.50:5555"
}

The device_serial field is optional for install and uninstall operations. When omitted, the active device is used, or the only ready device is selected automatically.

By default, uninstall_app removes the application and its data. Set keep_data to true to retain its data and cache directories using adb uninstall -k. Package names are validated before invoking ADB, and the tool only reports success when ADB explicitly returns Success.

Both installation and uninstallation are exposed as destructive MCP operations. Agents should verify the intended device and package before calling them.

Build Profiles

Builds are intentionally not arbitrary shell commands sent by the agent. The server owner declares allowed profiles in adb-mcp.config.json, and the MCP tool can only run those profiles.

Example:

{
  "projectRoot": "../MyAndroidTvApp",
  "profiles": [
    {
      "name": "debug",
      "description": "Gradle debug APK",
      "executable": "./gradlew",
      "args": ["app:assembleDebug"],
      "cwd": ".",
      "artifactPath": "app/build/outputs/apk/debug/app-debug.apk",
      "timeoutMs": 600000
    },
    {
      "name": "release",
      "description": "Gradle release APK",
      "executable": "./gradlew",
      "args": ["app:assembleRelease"],
      "cwd": ".",
      "artifactPath": "app/build/outputs/apk/release/app-release.apk",
      "timeoutMs": 900000
    }
  ]
}

run_build can be called with install_after_build: true when the profile declares an APK artifactPath.

Configuration

Environment variables:

• ADB_EXECUTABLE: ADB executable path. Defaults to adb.

• VEGA_EXECUTABLE: Vega CLI executable path used for Vega/Kepler backends. Defaults to vega.

• ADB_PROJECT_ROOT: project root used for default config and APK root. Defaults to the server working directory.

• ADB_APK_ROOT: directory from which APK installation is allowed. Defaults to ADB_PROJECT_ROOT.

• ADB_BUILD_CONFIG: path to build profile JSON. Defaults to adb-mcp.config.json in the server working directory when present.

• ADB_TIMEOUT_MS: default ADB command timeout. Defaults to 30000.

• ADB_MAX_OUTPUT_BYTES: default ADB output limit. Defaults to 5242880.

• ADB_SCREENSHOT_MAX_BYTES: maximum raw PNG size accepted from adb screencap. Defaults to 33554432, allowing 4K captures to be processed before applying the smaller delivery limit.

• ADB_SCREENSHOT_OUTPUT_MAX_BYTES: maximum optimized PNG size. Defaults to 1048576.

• ADB_SCREENSHOT_MAX_WIDTH: maximum delivered screenshot width. Defaults to 1280.

• ADB_SCREENSHOT_MAX_HEIGHT: maximum delivered screenshot height. Defaults to 720.

• ANDROID_EMULATOR_EXECUTABLE: Android Emulator executable. Defaults to $ANDROID_SDK_ROOT/emulator/emulator, $ANDROID_HOME/emulator/emulator, or emulator from PATH.

• ADB_ALLOWED_AVDS: optional comma-separated allowlist of AVD names.

• OBS_EXECUTABLE: OBS application name, .app path, or executable path. Defaults to OBS on macOS and obs elsewhere.

• OBS_WEBSOCKET_URL: OBS WebSocket endpoint. Defaults to ws://127.0.0.1:4455.

• OBS_WEBSOCKET_PASSWORD: OBS WebSocket authentication password.

• OBS_EMULATOR_SCENE / OBS_EMULATOR_SOURCE: configured OBS scene and source for emulator recording.

• OBS_PHYSICAL_DEVICE_SCENE / OBS_PHYSICAL_DEVICE_SOURCE: configured OBS scene and source for physical-device recording.

Local Development

npm install
npm run build
npm test