접근성 스냅샷과 대화형 명령을 통해 AI agent가 모바일, 웹, TV, 데스크톱 애플리케이션을 검사, 제어 및 검증할 수 있도록 지원합니다.
다른 이름 callstack/agent-device
- 스타
- 5,403
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- 0.21.37
- 마지막 커밋
- 2026년 11월 15일
- 라이선스
- MIT
agent-device MCP란?
agent-device은(는) MCP server입니다. 접근성 스냅샷과 대화형 명령을 통해 AI agent가 모바일, 웹, TV, 데스크톱 애플리케이션을 검사, 제어 및 검증할 수 있도록 지원합니다.
프로젝트 README에서 생성된 요약
agent-device MCP server 정보
agent-device는 AI 코딩 agent가 다양한 소프트웨어 환경과 상호작용할 수 있도록 특화된 레이어를 제공합니다. iOS, Android, HarmonyOS와 같은 모바일 플랫폼뿐만 아니라 tvOS, 웹, macOS, Linux에서 실행되는 애플리케이션을 검사, 제어 및 검증할 수 있습니다. 단순히 시각적인 스크린샷에만 의존하는 대신, 토큰 효율적인 접근성 스냅샷을 사용하여 agent가 역할, 레이블, 셀렉터를 통해 UI를 이해할 수 있도록 돕습니다.
개발자는 CLI, 타입이 지정된 Node.js API 또는 내장된 stdio MCP server 연결을 통해 이 기능을 워크플로우에 통합할 수 있습니다. 이 도구는 Claude Code, Cursor, Windsurf, Goose와 같은 인기 있는 AI 클라이언트와 함께 작동하도록 설계되었습니다. 병렬 워크트리 전반에 걸쳐 디바이스 액세스를 관리하며, BrowserStack 또는 AWS Device Farm과 같은 원격 디바이스 클라우드에 연결할 수 있습니다. 이를 통해 시뮬레이터 및 에뮬레이터에서의 로컬 디버깅이나 CI/CD 파이프라인 내의 자동화된 검증에 적합합니다.
활용 사례
- 1UI 변경 사항 검증agent가 새로운 화면을 구현한 후 iOS 시뮬레이터 또는 Android 에뮬레이터에서 실행하여 정상 작동 여부를 확인할 수 있습니다.
- 2애플리케이션 크래시 디버깅agent에게 특정 크래시를 재현하도록 지시하고 분석에 필요한 모든 로그를 수집하도록 할 수 있습니다.
- 3반복적인 워크플로우 자동화agent가 특정 사용자 흐름을 탐색하고 해당 단계를 스크립트로 저장하여 향후 지속적 통합(CI)에서 사용할 수 있습니다.
- 4성능 문제 분석이 도구를 통해 agent가 코드 변경으로 인해 React Native 애플리케이션에서 불필요한 리렌더링이 발생하는지 확인할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
agent-device MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 agent-device MCP 설치
$ claude mcp add agent-device -- npx -y agent-deviceCursor에 agent-device MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"agent-device": {
"command": "npx",
"args": [
"-y",
"agent-device"
]
}
}
}VS Code에 agent-device MCP 설치
.vscode/mcp.json
{
"servers": {
"agent-device": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"agent-device"
]
}
}
}VS Code CLI에 agent-device MCP 설치
$ code --add-mcp '{"name":"agent-device","type":"stdio","command":"npx","args":["-y","agent-device"]}'Claude Desktop에 agent-device MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"agent-device": {
"command": "npx",
"args": [
"-y",
"agent-device"
]
}
}
}Codex에 agent-device MCP 설치
$ codex mcp add agent-device -- npx -y agent-deviceCodex config.toml에 agent-device MCP 설치
~/.codex/config.toml
[mcp_servers.agent-device] command = "npx" args = ["-y", "agent-device"]
Gemini CLI에 agent-device MCP 설치
$ gemini mcp add -s user agent-device npx -- -y agent-deviceGemini settings.json에 agent-device MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"agent-device": {
"command": "npx",
"args": [
"-y",
"agent-device"
]
}
}
}자동 검사
2026년 11월 12일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음통과
README
GitHub에서 보기agent-device
Open source device layer for AI coding agents. Let coding agents control mobile, web, TV, and desktop apps on devices and simulators, locally or in the cloud, through a CLI, built-in MCP server, or typed Node.js API.
Let your coding agent verify its changes in the running app. agent-device lets agents inspect, control, debug, and verify apps on iOS, Android, and HarmonyOS (simulators, emulators, and physical devices), plus tvOS, Android TV, Fire TV (Fire OS), Amazon Vega OS TV (Vega Virtual Device), web, macOS, and Linux. Agents read token-efficient accessibility snapshots instead of reasoning over screenshots alone, act through refs and selectors, and save evidence for review. It also coordinates device access across parallel agent worktrees and connects to remote device clouds.
Works with Claude Code, Codex, Cursor, Windsurf, Cline, Goose, and any agent that can run a CLI or connect over MCP, or as the runtime under agents you build with the AI SDK or Eve. Developers at Expensify, Shopify, and others use it to verify their apps.
Quick start
Install the CLI and check setup. It requires Node.js 22.12 or newer; web automation requires Node.js 24 or newer. See Installation for target requirements.
npm install -g agent-device@latest
agent-device doctor
agent-device help workflow
Run doctor yourself before you hand the CLI to an agent. help workflow links to the guides for debugging, replay, and profiling.
Drive an app from the CLI
Add a contact in the built-in iOS Contacts app:
# Start a session.
agent-device open Contacts --platform ios
# Inspect the screen. The example below shows the output; refs vary.
agent-device snapshot -i
# @e2 [button] "Add"
# Use the ref and wait for the UI to settle.
agent-device press @e2 --settle
# The diff includes:
# + @e7 [text-field] "First name"
agent-device fill @e7 "Ada" --settle
# The next diff shows changed values and current refs:
# - @e7 [text-field] "First name"
# + @e14 [text-field] "Ada"
# = @e15 [text-field] "Last name"
# Capture evidence and close the session.
agent-device screenshot ./contact-form.png
agent-device close
Refs are valid only in the latest output: after a --settle command, use the refs in its diff, and take a new snapshot only if the diff omits what you need. Snapshots come from the app's accessibility tree, so clear labels, roles, and test IDs make agent runs more reliable; use screenshots and video as evidence or when accessibility data is poor.

Add MCP tools to your agent
agent-device mcp starts the official stdio MCP server, exposing the installed commands as structured tools over the same execution path as the CLI:
{
"mcpServers": {
"agent-device": {
"command": "agent-device",
"args": ["mcp"]
}
}
}
See AI agent setup for per-client setup and when to prefer plain CLI over MCP.
Script it from Node.js
createAgentDeviceClient() gives Node.js code typed access to the same commands, as model tools in your own agent or from orchestration code:
import { createAgentDeviceClient } from 'agent-device';
const client = createAgentDeviceClient({ session: 'qa-run' });
try {
await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' });
const snapshot = await client.capture.snapshot({ interactiveOnly: true });
const button = snapshot.nodes.find((node) => node.role === 'button');
if (button) await client.interactions.press({ ref: button.ref });
} finally {
await client.sessions.close();
}
See the Node.js API, the runnable examples, and the AI SDK and Eve integration guides.
What agents can do
- Inspect app state through accessibility snapshots, refs, and selectors, and profile React Native renders to find what makes an interaction slow.
- Act on visible UI by tapping or pressing elements, filling fields, scrolling, making gestures, waiting, asserting state, and handling alerts.
- Diagnose failures with screenshots, video, logs, traces, network data, performance samples, crash details, and React profiles.
- Repeat workflows by saving working steps as
.adscripts for local use or CI. Export strict Maestro YAML when needed.
See Commands for the commands and evidence each target supports.
What to ask your agent
With the CLI installed, prompts like these work end to end:
- "Implement the onboarding screen, run it on the iOS simulator and Android emulator, and attach screenshots."
- "Reproduce this crash and capture the logs that lead up to it."
- "Check whether this change causes unnecessary React Native re-renders."
- "Explore the checkout flow once, save it as a replay script, and run it in CI."
- "Verify this pull request on a physical device and attach reviewable evidence."
Next steps
- AI agent setup: skills, project rules, and per-client setup for Cursor, Codex, Claude Code, Windsurf, and others.
- Quick start: open an app, read its UI, and interact with it from the command line.
- Replay and E2E testing and Debugging and profiling: repeatable tests and bug hunting.
Where to run agent-device
The same session and evidence model works at every step: the agent explores the app, captures evidence, saves a replay, runs it in CI, and moves onto remote devices.
| Path | Best for | Start with |
|---|---|---|
| Local | Trying commands and debugging apps on simulators, emulators, physical devices, macOS, and Linux. | Follow the Quick Start. |
| CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the EAS workflow template. |
| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a remote proxy, connect a device cloud (BrowserStack, AWS Device Farm, TestMu AI, Limrun), or contact Callstack for team QA. |
How it works
agent-device keeps device state in sessions. It uses a local accessibility bridge for iOS Simulator snapshots and XCTest for iOS interactions, physical iOS, and tvOS; ADB and the snapshot helper on Android, Android TV, and Fire OS; HDC and ArkUI uitest on HarmonyOS; Vega CLI/VDA on the Vega Virtual Device; a local helper on macOS, including Electron and other Chromium-based apps through the accessibility tree; and AT-SPI on Linux.
Support depth varies by target. Some backends, such as HarmonyOS and Vega OS, cover a subset of commands; run agent-device capabilities --platform <platform> to see what a target supports. The capabilities matrix shows which commands each target, desktop, web, and cloud provider supports.
Sessions are scoped to the caller's git worktree, and host-local device claims stop parallel agents from taking over each other's simulators and emulators. Run agent-device device status to inspect ownership without a daemon, and agent-device device release --stale to release claims whose owner is provably no longer running. The same commands drive hosted devices on BrowserStack, AWS Device Farm, TestMu AI, and Limrun.
agent-device uses the inspect-act-verify process from Vercel's agent-browser for mobile, TV, and desktop apps. Basic --platform web support runs agent-browser in the same session and replay system.
FAQ
What is agent-device?
agent-device is a command-line tool and MCP server that lets AI coding agents inspect, control, and verify mobile apps and save evidence for review. It supports iOS, Android, HarmonyOS, TV, web, macOS, and Linux.
Is there an MCP server for mobile app automation?
Yes. agent-device mcp starts the official stdio MCP server. The Quick start above has the client config, and AI agent setup covers per-client details.
Does it work with React Native, Expo, Flutter, and native apps?
Yes. agent-device supports native iOS and Android apps, plus React Native, Expo, and Flutter apps on supported targets. The commands and evidence vary by target.
How is it different from mobile MCP servers?
The MCP server is one entry point to the same runtime used by the CLI and typed Node.js API. Sessions, device ownership, selectors, evidence, replay, CI workflows, and cloud routing stay consistent across all three.
Can I build my own agent or QA product on agent-device?
Yes. The typed Node.js client is a public surface over that same runtime, so an agent you build inherits everything above. Start from the Node.js API, AI SDK, or Eve guides.
How is it different from Appium, Detox, or Maestro?
With agent-device, an agent reads app state and chooses each command at run time. For stable, repeatable test suites, use e2e, a TypeScript testing framework for web and mobile apps. agent-device can also save its runs as .ad scripts or export them as strict Maestro YAML.
Can agent-device run in CI?
Yes. Record a run as an .ad script, replay it in CI, and keep the screenshots and logs as artifacts; the EAS workflow template is a working example.
Articles and videos
Articles
- Build an AI QA agent for Expo apps with EAS Workflows
- Agent Device: iOS & Android automation for AI agents
- Building mobile QA agents with Vercel Eve
- How we optimized Agent Device for mobile app automation
Videos
- Verifying mobile apps with agent-device
- Using agent-device in an AI coding workflow
- Cloud agents that test mobile apps on real devices
Who uses agent-device?
Teams and developers at Callstack, JPMorgan Chase, Expensify, Shopify, Kindred, Total Wine & More, LegendList, HerLyfe, App & Flow, and others use agent-device.
Documentation
Contributing
See CONTRIBUTING.md.
Made at Callstack
agent-device is open source under the MIT license. Visit agent-device.dev or contact Callstack.
agent-device MCP 질문
agent-device MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add agent-device -- npx -y agent-device를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
agent-device MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
agent-device란 무엇인가요?
AI 코딩 agent가 모바일 앱을 검사, 제어 및 검증하고 검토를 위한 증거를 저장할 수 있도록 지원하는 CLI 도구이자 MCP server입니다.
React Native, Expo, Flutter 및 네이티브 앱에서도 작동하나요?
네, 네이티브 iOS 및 Android 앱은 물론 지원되는 플랫폼의 React Native, Expo, Flutter 앱을 지원합니다.
모바일 앱 자동화를 위한 MCP server가 있나요?
네, 'agent-device mcp'를 실행하면 명령을 구조화된 도구로 노출하는 공식 stdio MCP server가 시작됩니다.
agent-device를 사용하여 직접 agent나 QA 제품을 만들 수 있나요?
네, 타입이 지정된 Node.js client를 사용하여 직접 agent나 오케스트레이션 코드를 구축할 수 있습니다.