MCP Server

Active

MIT

agent-device MCP Server

io.github.callstackincubator/agent-device

Give AI agents hands and eyes to inspect, control, and debug real iOS, Android, TV, and desktop apps.

What is the agent-device MCP server?

agent-device is a device automation CLI (usable as an MCP server) that lets AI coding agents inspect, control, and debug real iOS, Android, TV, desktop, and web apps. It gives agents structured accessibility snapshots, semantic element refs, and on-demand evidence capture (screenshots, videos, logs, traces) so they can verify actual app behavior instead of just reasoning about code. It works with native iOS/Android apps as well as Expo, Flutter, and React Native apps across simulators, emulators, physical devices, and desktop targets.

agent-device gives AI agents a real-app feedback loop: open an app, inspect the current screen via accessibility-tree snapshots with interactive refs (like @e3), interact with elements (tap, type, scroll, gesture, wait, assert), and capture evidence (screenshots, videos, logs, traces, network traffic, performance samples, crash context, React profiles) only when needed. It supports iOS Simulator, Android Emulator, physical devices, tvOS, Android TV, macOS, Linux, and desktop apps, plus minimal web support via agent-browser. Exploratory interactions can be recorded as replayable `.ad` scripts or exported to Maestro YAML for CI/e2e use, making it useful both for local dogfooding and automated PR/merge validation.

How to install agent-device

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

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

Cursor

~/.cursor/mcp.json

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

Windsurf

~/.codeium/windsurf/mcp_config.json

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

VS Code

.vscode/mcp.json

{
  "servers": {
    "agent-device": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "agent-device"
      ]
    }
  }
}

Claude Code

claude mcp add agent-device -- npx -y agent-device

Tools & capabilities

Tools this server exposes to the agent.

apps — List available apps on a given platform (e.g., iOS, Android)
open — Open/launch an app on a device or simulator to start a session
snapshot — Capture a structured accessibility snapshot of the current screen, returning interactive element refs (e.g., @e1, @e2)
fill — Type text into an interactive element identified by its ref
screenshot — Capture a screenshot of the current app state as evidence
close — Close the current app session

Use cases

Verify mobile changes on real devices, simulators, and emulators before review or merge
Give AI coding agents a real app feedback loop while implementing features
Debug regressions with screenshots, logs, traces, network evidence, and crash context
Profile performance issues with CPU/memory samples and React render profiles
Turn exploratory app interactions into replayable e2e checks for CI

agent-device MCP server FAQ

What is agent-device?

It's a device automation CLI for AI mobile app testing that lets AI agents verify real apps on iOS, Android, TV, desktop, simulators, emulators, and physical devices.

Is agent-device free?

Yes, it is open source and MIT licensed. There is also a paid Agent Device Cloud offering for remote/cloud execution on managed devices.

Does it work with React Native, Expo, Flutter, and native apps?

Yes. It works with native iOS and Android apps, Expo apps, Flutter apps, React Native apps, TV apps, and desktop apps that run on supported targets.

How do I install agent-device?

Install the CLI globally with `npm install -g agent-device@latest`, then run it from your agent terminal (Cursor, Codex, Claude Code, Windsurf, etc.). Prerequisites include Node.js 22+ (Node 24+ for web), Xcode for iOS/tvOS/macOS, and Android SDK + ADB for Android.

How is it different from Appium, Detox, or Maestro?

Appium, Detox, and Maestro are traditional mobile automation frameworks, while agent-device is optimized for AI agents to inspect app state, interact semantically, capture evidence, debug, profile, and convert explorations into replayable checks (including strict Maestro YAML export).

What authentication or permissions are required?

No special auth is described; setup requires platform tooling like Xcode, Android SDK/ADB, and macOS Accessibility permission for desktop automation, depending on target platform.

README (reference)

Source of truth, from the repository.

agent-device

Mobile app verification for AI agents.

A device automation CLI for real apps on iOS, Android, TV, web, and desktop. Agents get token-efficient snapshots, semantic refs, and evidence captured only when needed.

agent-device lets coding agents open apps, inspect the current UI, interact with visible elements, and collect debugging evidence through one CLI. Use it when an agent needs to verify what actually happens on a device, not just reason about code.

The CLI is the agent's hands, eyes, and evidence collector; it is not the brain. Your coding agent or QA harness reads the task, interprets the current screen, chooses the next command, and decides whether the result satisfies the test. agent-device keeps that loop grounded in structured accessibility data, deterministic actions, and files an engineer can inspect.

If you know Vercel's agent-browser, agent-device is the same idea for mobile, TV, and desktop apps. Minimal --platform web support reuses agent-browser when a browser session needs to fit into the same command/session/replay loop.

It works with native iOS and Android apps, plus apps built with Expo, Flutter, and React Native, as long as the target can run on a supported device, simulator, emulator, or desktop environment.

agent-device demo showing Codex using agent-device to create a new contact in the iOS Contacts app from a simple prompt

Capabilities

Inspect real app UI through structured accessibility snapshots, interactive refs like @e3, selectors, and React Native component trees.
Interact by opening apps, tapping, typing, scrolling, performing gestures, waiting, asserting state, handling alerts, and closing sessions.
Capture evidence with screenshots, videos, logs, traces, network traffic, performance samples, crash context, and React profiles.
Replay workflows by recording .ad scripts for local runs, CI, repeatable e2e checks, and strict Maestro YAML export when a flow needs to run in Maestro.
Run across platforms with iOS Simulator automation, Android Emulator automation, physical devices, tvOS, Android TV, macOS, Linux, and desktop app automation, so agents can see and feel the app they work on.

Use Cases

Verify mobile changes on real devices, simulators, and emulators before review or merge.
Give AI coding agents a real app feedback loop while they implement features.
Debug regressions with screenshots, logs, traces, network evidence, and crash context.
Profile performance issues with CPU/memory samples and React render profiles when needed.
Turn exploratory app interactions into replayable e2e checks for CI.
Use one agent workflow across native iOS, Android, Expo, Flutter, React Native, TV, and desktop apps.

Sketch showing agent-device as the live app verification layer in the agentic development loop

Quick Start

Install the CLI:

npm install -g agent-device@latest
agent-device --version
agent-device help workflow

The installed CLI help is the source of truth for agents. Start with agent-device help workflow, then follow the topic-specific help when a task needs dogfooding, debugging, replay, or React Native profiling.

Prerequisites depend on the target platform: Node.js 22+, Xcode for iOS/tvOS/macOS targets, Android SDK + ADB for Android, and macOS Accessibility permission for desktop automation. Web automation requires Node 24+. See Installation for platform setup.

Try the basic loop:

# Find an app.
agent-device apps --platform ios
agent-device apps --platform android

# Start a session.
agent-device open SampleApp --platform ios

# Inspect the current screen. -i returns interactive elements only.
agent-device snapshot -i
# @e1 [heading] "Settings"
# @e2 [button] "Sign In"
# @e3 [text-field] "Email"

# Act, capture evidence, and close.
agent-device fill @e3 "test@example.com"
agent-device screenshot ./artifacts/settings.png
agent-device close

Snapshots assign refs like @e1, @e2, and @e3 to elements on the current screen. Refs from the latest snapshot are immediately actionable; after scrolling or changing screens, take a fresh snapshot.

Snapshots come from the app's accessibility tree, so high-quality labels, roles, and test IDs make agent runs far more reliable. Use screenshots and videos as evidence or visual fallback, but prefer refs and selectors for actions and assertions whenever the UI exposes enough structure.

Next Steps

Set up your agent: run the CLI from Cursor, Codex, Claude Code, Windsurf, or another agent terminal. For skills, rules, direct MCP tools, and client-specific setup, see AI Agent Setup.
Try the sample app: clone the repo and run the bundled Expo fixture when you want a guided first dogfood run with screenshots, replay, and performance evidence. See Quick Start.
Go deeper: use Commands, Replay & E2E, and Debugging & Profiling for production workflows.

Articles & Videos

Articles

Videos

Where To Run agent-device

Path	Best for	Start with
Local	Exploration, debugging, and development loops on simulators, emulators, physical devices, macOS apps, and Linux desktop targets.	Follow the Quick Start.
CI/CD	Automated PR and merge validation with replay scripts and captured artifacts.	Try the EAS workflow template. GitHub Actions template coming soon.
Cloud / remote execution	Linux runners, managed devices, and remote execution.	Use Agent Device Cloud, see Commands for remote profiles, or contact Callstack for team-scale QA.

How It Works

agent-device runs session-aware commands through platform backends: XCTest for iOS and tvOS, ADB plus the Android snapshot helper for Android, a local helper for macOS desktop automation, and AT-SPI for Linux desktop targets.

Node consumers can use the typed client and public subpaths for bridge integrations. agent-device/android-adb exposes the Android ADB provider contract, logcat/clipboard/keyboard/app helpers, and port reverse management.

FAQ

What is agent-device?

agent-device is a device automation CLI for AI mobile app testing. It lets AI agents verify real apps on iOS, Android, TV, desktop, simulators, emulators, and physical devices.

Does it work with React Native, Expo, Flutter, and native apps?

Yes. agent-device works with native iOS and Android apps, Expo apps, Flutter apps, React Native apps, TV apps, and desktop apps that run on supported targets.

How is it different from Appium, Detox, or Maestro?

Appium, Detox, and Maestro are traditional mobile automation frameworks. agent-device is optimized for AI agents that need to inspect app state, interact semantically, capture evidence, debug, profile, and turn useful explorations into replayable checks.

Used By

Used by teams and developers at Callstack, JPMorgan Chase, Expensify, Shopify, Kindred, Total Wine & More, LegendList, HerLyfe, App & Flow, and more.

Documentation

Contributing

See CONTRIBUTING.md.

Made at Callstack

Apache-2.0

View repository →