Set up the agent-device MCP server

agent-device is not a hosted service but a locally installed command-line tool that also provides an MCP server. This guide covers the steps from installation to a first connection with an AI client.

Prerequisites

You need Node.js 22.12 or newer (24 or newer for web mode), plus — depending on the target platform — the matching native toolchain: Xcode with an installed iOS Simulator for iOS and tvOS, the Android SDK with USB debugging enabled and an authorized ADB connection for Android and Android TV, the HarmonyOS toolchain with HDC for HarmonyOS devices, the Vega CLI/VDA for the Amazon Vega OS TV platform, and, on Linux, access to the AT-SPI accessibility bus. On macOS, the local helper needs the accessibility permission under the privacy section of System Settings.

Installation

Install the package globally via npm:

npm install -g agent-device@latest

Then run agent-device doctor. The command checks the local environment — installed SDKs, connected devices, and granted permissions — and reports any missing prerequisites before you hand the tool to an agent. agent-device help workflow links to matching guides for debugging, replay, and profiling that always match the installed version.

Connecting the MCP server to a client

The agent-device mcp command starts the official stdio MCP server, exposing the installed CLI commands as structured tools. In clients such as Claude Code or Cursor, register it with this configuration:

{
  "mcpServers": {
    "agent-device": {
      "command": "agent-device",
      "args": ["mcp"]
    }
  }
}

Since the server runs over stdio, no additional authentication or URL is required — the client starts the process directly and communicates over standard input/output. Per the project, the same basic configuration works analogously with Codex, Windsurf, Cline, and Goose.

Running a first session

Test the setup directly via the CLI before handing it to an agent. A simple run against the built-in iOS Contacts app looks like this:

agent-device open Contacts --platform ios
agent-device snapshot -i
agent-device press @e2 --settle
agent-device screenshot ./evidence.png
agent-device close

snapshot -i shows interactive elements with their references; after each command run with --settle, the output includes a diff with fresh, valid references. References from older output become stale — request a new snapshot whenever you need one.

Checking and releasing device state

With parallel agents or worktrees, agent-device device status shows which process currently holds which device, and agent-device device release --stale frees claims left behind by processes that are no longer running.

Common pitfalls

A frequent issue is an outdated Node.js version — web mode in particular fails under Node.js 22 because it requires version 24; agent-device doctor flags this upfront. On Android, connections often fail due to unauthorized USB debugging: run a plain adb devices to confirm the device shows as "device" rather than "unauthorized". On macOS, the local helper aborts without the accessibility permission, which must be granted manually in System Settings for the terminal or editor program actually running the command. Using stale references from an older snapshot usually causes the next command to report that the element was not found — a fresh snapshot call resolves that.