Karagöz
Karagöz exposes cross-platform mobile device automation to an MCP client across Android emulators/devices and iOS simulators/iPhones.
Discover connected devices and simulators (
devices) and diagnose tooling (doctor).Inspect the UI via
ui_treeand capture full-resolution screenshots (screenshot).Interact with the UI:
tap,long_press,double_tap,swipe,text, andkey.Manage apps:
install,launch,open_url,terminate, anduninstall.Read device and app logs (
logs).Install or remove Karagöz's iPhone automation runner (
install_runner,uninstall_runner) for iOS UI inspection and input.
Allows automating Android emulators and physical devices via adb, including device selection, screenshots, accessibility UI tree inspection, touch and text input, app lifecycle management, and log capture.
Allows automating iOS simulators and physical devices via simctl and WebDriverAgent/XCTest, including device selection, screenshots, accessibility UI tree inspection, touch and text input, app lifecycle management, and log capture.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Karagöz Take a screenshot of the Android emulator and show the UI tree."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Karagöz
Device automation for mobile apps. One tool for four targets: Android emulator, Android physical device, iOS simulator, iOS physical device. It is a CLI, and karagoz mcp serves the same commands to an AI agent as an MCP server.
Contents
Related MCP server: mobile-mcp
Why karagoz
adb, simctl and devicectl run the command; karagoz tells you what the command actually did.
What happened, as a code.
am force-stopon an app that is not installed says nothing,simctlanddevicectlreport success for uninstalling an app that is not there, and Android answers a missing package with the code it gives a package it will not remove. karagoz checks first and returnsAPP_NOT_FOUND. A refused install isINSTALL_FAILEDwith the platform's own code inreason, not text to parse.One contract on four targets. The same commands, flags, device selection, output and error codes on an Android emulator, an Android phone, an iOS simulator and an iPhone. The MCP server returns the CLI's JSON line unchanged.
The accessibility tree first. To see the screen, read
ui-treebefore taking a screenshot. The tree is text a program can search, costs a few hundred to a few thousand tokens, and gives the bounds needed to tap. A screenshot is written to disk at full resolution and returned as a path, with its pixel size, logical size and scale (and safe area on Android) to measure against; the CLI never prints the image.It installs only what you ask and starts no daemon of its own. Each command exits when it answers, and
karagoz mcpexits with its client. Only karagoz's runner stays up between calls, and it stops 10 minutes after its last use. The one thing karagoz installs unasked is that runner, on a simulator of a Mac that never had Xcode 27 (FAQ).
Scope
karagoz is the primitive layer. Each command does one thing and exits.
Not a test framework. No assertions, no test runner, no recorded flows, no retry policy, no reports.
tap --timeoutwaits for a node to appear; it never repeats an action.Not a design comparison tool. Figma diffing, measurement and reporting belong a layer above. karagoz produces the raw input, and the metadata to measure it with, but does not interpret it.
Status
Early development. Every command runs on all four targets, except install-runner, which runs only on iPhones, and uninstall-runner, which runs on iPhones and on simulators of a Mac that never had Xcode 27. For Windows and Linux, see the FAQ.
Getting started
Requirements
Node 22 or newer.
Android:
adbfrom Android platform-tools, and a running emulator or a phone with USB debugging on.iOS simulator (macOS): Xcode, opened once, and a booted simulator.
tap,long-press,double-tap,swipe,textandkeyneed Xcode 27 or newer, or a Mac that never had Xcode 27, where they go through karagoz's runner.iPhone (macOS): Xcode 15 or newer (27 for
screenshot), the iPhone paired with the Mac, and Developer Mode on.ui-treeand the input commands also need a USB cable, UI Automation on, and karagoz's runner, whichinstall-runnerinstalls.
What each command needs, and how karagoz finds adb and Xcode.
Install
npm install -g karagoz-mcp
karagoz devicesOr without installing: npx -y karagoz-mcp devices. To build from source: Development.
Quick start
$ karagoz devices
Found 1 device:
Medium_Phone_API_37.0 • emulator-5554 • emulator • Android 17 (API 37) • device
Missing a device? Run karagoz doctor.When stdout is not a terminal, as in a pipe or Claude Code's shell, every command prints one line of JSON, shown here; at a terminal the other commands indent it.
$ karagoz tap --text Chrome
{"device":"emulator-5554","x":667.5,"y":2002.5,"element":{"class":"android.widget.TextView","text":"Chrome","contentDesc":"Chrome","clickable":true,"longClickable":true,"focusable":true,"bounds":[581,1905,754,2100]}}
$ karagoz key HOME
{"device":"emulator-5554","key":"KEYCODE_HOME","code":3}
$ karagoz screenshot --out home.png
{"path":"/Users/me/home.png","device":"emulator-5554","pixels":{"width":1080,"height":2400},"logical":{"width":411.42857142857144,"height":914.2857142857143},"scale":2.625,"safeArea":{"top":63,"right":0,"bottom":63,"left":0},"rotation":0}karagoz ui-tree prints the screen's accessibility tree; tap --text above found its target in that tree.
Claude Code with the MCP server on an iOS simulator, in real time. The right side lists each karagoz call and part of the JSON it returned.

MCP server
karagoz mcpStarts an MCP server for an AI agent on stdin and stdout. It opens no port: the client starts the process and talks to it over stdio. The 18 commands are its tools, and each tool returns the JSON line the CLI prints.
Claude Code
claude mcp add karagoz -- npx -y karagoz-mcp mcpClaude Desktop
Download karagoz.mcpb from the latest release and open it. Desktop installs it as an extension.
Cursor
Or in .cursor/mcp.json:
{"mcpServers":{"karagoz":{"type":"stdio","command":"npx","args":["-y","karagoz-mcp","mcp"]}}}VS Code
In .vscode/mcp.json:
{"servers":{"karagoz":{"type":"stdio","command":"npx","args":["-y","karagoz-mcp","mcp"]}}}Codex
codex mcp add karagoz -- npx -y karagoz-mcp mcpThen add these two lines under [mcp_servers.karagoz] in ~/.codex/config.toml. The command cannot write them, and without them Codex hides ANDROID_HOME from karagoz and cuts long calls short:
env_vars = ["ANDROID_HOME", "ANDROID_SDK_ROOT", "KARAGOZ_DEVICE", "ANDROID_SERIAL", "DEVELOPER_DIR"]
tool_timeout_sec = 600Agent instructions
Optional. Add this to your CLAUDE.md, AGENTS.md or your agent's rules, or ask your agent to add it, and it uses karagoz for a request about a device without being told to:
## Mobile devices
For anything on an Android emulator or phone, an iOS simulator or an iPhone (reading the screen, tapping, typing, screenshots, installing or launching an app, logs), use karagoz instead of calling adb, xcrun simctl, devicectl or xcodebuild yourself. Use the karagoz MCP tools when they are available; otherwise run `npx -y karagoz-mcp <command>`. Read the screen with ui-tree before taking a screenshot, tap by text or id, and branch on error.code.Token cost
What the server adds to a Claude Code session, measured on 2026-10-30 with Claude Code 2.1.306 and claude-opus-5-5: input tokens of the first API call with karagoz registered, minus the same call with no MCP server.
Case | Tokens |
Every session, tool search on (the default): the 18 tool names and | 410 |
All 18 definitions, loaded by one | 3,634 |
Every session, tool search off ( | 3,476 |
The tools/list result is 9,547 characters, instructions 398. One ui_tree of the launcher home screen is 5,127 characters (11,767 with detail: full).
Things to ask your agent
Once the server is registered, describe the task to your agent. It reads the screen with ui_tree and calls one tool per step.
"Open Settings on the emulator and turn on dark mode."
"Install
./build/app-debug.apk, open it, and tell me what the first screen shows.""On the sign-in screen, type
test@example.cominto the email field and tap Continue.""Open
myapp://orders/42on the iOS simulator and take a screenshot.""The app closes right after launch on the emulator. Show me its last 50 log lines."
Commands
Command | Does |
List connected devices | |
Save a full-resolution PNG and return its path with scale metadata | |
Return the accessibility tree of the focused window | |
Tap a point, or a node found by text or id | |
Press and hold a point or a node | |
Tap a point or a node twice | |
Swipe between two points | |
Type text into the focused field | |
Press a key | |
Install or replace an app | |
Start an app as its launcher icon does | |
Open a URL or deep link in the app that handles it | |
Stop every process of an app | |
Remove an app | |
Read the device log | |
Report which adb and Xcode karagoz uses | |
Build karagoz's runner and install it on an iPhone | |
Remove karagoz's runner from an iPhone or a simulator | |
Start the MCP server on stdio |
Every command except devices, doctor and mcp works on one device. When more than one is listed, pick it with --device <id or name> or KARAGOZ_DEVICE: Device selection.
Output and errors
Every command prints one line of JSON on stdout: its result with exit code 0, or {"error":{"code":"<CODE>","message":"<text>"}} with exit code 1. Branch on error.code, not on the message. At a terminal, devices and doctor print a summary instead and the other commands indent their JSON; when stdout is not a terminal, as in a pipe, the line is printed.
Output, arguments and coordinates · Error codes · Known limitations
How it works
A command finds the device, runs the platform's own tool for the job, and turns the answer into one JSON line. karagoz mcp calls the same code.
Target | Screen | Accessibility tree | Input | Apps | Logs |
Android emulator and phone |
|
|
|
|
|
iOS simulator |
| karagoz's Swift helper, compiled on first use with Xcode's | The helper: the simulator's input service, and XCUIAutomation for |
|
|
iPhone |
| karagoz's runner, an XCUITest bundle that | karagoz's runner |
| The phone's log relay over USB, read with macOS's |
FAQ
Nothing by itself, with one exception: on a Mac that never had Xcode 27, the first tap, long-press, double-tap, swipe, text or key on a simulator installs karagoz's runner there (Requirements). Typing text outside ASCII on Android copies a small helper to /data/local/tmp and deletes it when the call ends (text).
A Mac with Xcode and the iPhone paired, with Developer Mode on. Reading the screen and input also need a USB cable, UI Automation on, and karagoz's runner, installed once with install-runner. A free Apple ID signs the runner for 7 days (Known limitations).
The tree answers most questions about a screen as text. karagoz keeps the PNG at full resolution on disk, with the scale needed to measure against it. Over MCP, inline: true also returns the image, which the client scales down, so take coordinates from the tree (MCP results).
iOS targets need macOS. Android targets need only Node and adb, and karagoz looks for adb in the Windows and Linux SDK folders too. No device command has been run on either system yet. On Linux, CI runs the type check, lint, build and the smoke tests that need no device.
On Android only one UiAutomation client can be connected, so ui-tree, and a tap by --text or --id, return AUTOMATION_BUSY while another holds it. On an iOS simulator, text fails the same way while a UI test runs (Error codes).
Contributing
Bug reports and pull requests are welcome. CONTRIBUTING.md covers what to put in an issue, the checks a pull request needs, and what device data must never be posted.
License
MIT © 2026 Yılmaz Yağız Dokumacı
Available Tools
18 toolsdevicesList devicesARead-only
List Android devices and emulators, running iOS simulators, and iPhones connected to this Mac.
Inputs: no named parameters.
doctorCheck adb and XcodeARead-only
Report which adb and Xcode tools karagoz uses, their versions, and how to fix one that is missing, old or broken.
Inputs: no named parameters.
double_tapDouble-tapA
Double-tap x, y in physical pixels, or the center of the node whose text or contentDesc (iOS: label or value) equals text, or whose resource id (iOS: identifier) matches id. An iPhone needs install_runner once.
Inputs: x, y, id, text, +2 more.
installInstall an appADestructive
Install an .apk, or a .app or .ipa on an iOS simulator or iPhone, or replace the installed version of the same app. An iPhone takes only a build signed for it; karagoz does not re-sign. Times out after 30 s plus 1 s per MB.
Inputs: apk (required), device.
install_runnerInstall karagoz's iPhone runnerA
Build karagoz's runner with your Apple team and install it on a paired iPhone over USB; ui_tree, tap, swipe, text and key need it there.
Inputs: team, device.
keyPress a keyB
Press one key.
Inputs: key (required), device.
launchLaunch an appA
Start an app as its launcher icon does. On iOS it returns before the app is in front.
Inputs: package (required), device.
logsRead device logsARead-only
Read the newest device log records, oldest first. On iOS without since: the last minute, or the last hour with package. An iPhone read takes about 10 s.
Inputs: lines, since, device, package.
long_pressLong-pressA
Long-press x, y in physical pixels, or the center of the node whose text or contentDesc (iOS: label or value) equals text, or whose resource id (iOS: identifier) matches id. An iPhone needs install_runner once.
Inputs: x, y, id, text, +3 more.
open_urlOpen a URLA
Open a URL in the app that handles it, or in the app named by app. On iOS it returns before the app is in front, and a simulator may first ask "Open in ?".
Inputs: url (required), app, device.
screenshotTake a screenshotA
Save a full-resolution PNG of the screen and return its path with size, scale and safe area. Use ui_tree to read the screen; inline only to look at the image.
Inputs: out, device, inline.
swipeSwipeA
Swipe from x1, y1 to x2, y2 in physical pixels. An iPhone needs install_runner once.
Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +2 more.
tapTapA
Tap x, y in physical pixels, or the center of the node whose text or contentDesc (iOS: label or value) equals text, or whose resource id (iOS: identifier) matches id. An iPhone needs install_runner once.
Inputs: x, y, id, text, +2 more.
terminateStop an appB
Force-stop every process of an app.
Inputs: package (required), device.
textType textA
Type into the focused field. Any text; on Android, text beyond ASCII is pasted through the clipboard and the old clip put back. An iPhone needs install_runner once.
Inputs: text (required), device.
ui_treeRead the UI treeARead-only
Return the focused window's accessibility tree as JSON, compact by default: nodes with no text, label or action and nodes off screen are left out. Node bounds [left, top, right, bottom] are the physical pixels tap and swipe take. On an iPhone it needs karagoz's runner: install it once with install_runner.
Inputs: detail, device.
uninstallUninstall an appCDestructive
Remove an app.
Inputs: package (required), device.
uninstall_runnerRemove karagoz's iPhone runnerBDestructive
Remove karagoz's runner and its provisioning profile from an iPhone.
Inputs: device.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools have a clearly distinct purpose: device discovery, screenshots, UI inspection, gestures, app lifecycle, logs, and setup are separated. The only plausible overlaps are install/uninstall versus install_runner/uninstall_runner and launch versus open_url, but their descriptions make the target objects clear.
All tool names use lower_snake_case, making the set predictable to read. However, naming mixes bare imperative verbs (tap, swipe, install, launch) with noun/resource names (devices, screenshot, ui_tree, doctor, logs), so it is not a uniform verb_noun convention.
18 tools is slightly above the typical 3-15 range, but each maps to a real mobile automation need. Cross-platform device setup, runner management, UI interaction, and app lifecycle operations justify the size without obvious filler.
The surface covers device discovery, UI inspection, gestures, text/key input, app install/uninstall/launch/terminate, logs, and setup. Minor gaps exist for multi-touch gestures, hardware button shortcuts beyond key, and explicit waits, but agents can generally work around them.
Maintenance
Related MCP Connectors
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables AI agents to interact with Android devices through UI manipulation, screen capture, touch gestures, text input, and app management via ADB. Provides comprehensive mobile automation capabilities including element detection, navigation, and application control for Android device testing and interaction.961 PyPI2-
- AlicenseAqualityCmaintenanceEnables agents and LLMs to interact with native iOS and Android applications and devices via structured accessibility snapshots or coordinate-based taps, supporting simulators, emulators, and real devices.3945,799 npmApache 2.0
- AlicenseCqualityBmaintenanceEnables AI agents to control Android phones, emulators, redroid containers, iOS devices, and cloud-hosted devices through a perceive-act-verify loop of screen reading, taps, gestures, typing, and app launching. Exposes 138 tools for driving screens, elements, and files over adb, Portal APIs, and ios-portal without running ARM-only code on the device.949 npm1MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to see and control Android devices through ADB and scrcpy, supporting screenshots, input, app management, UI automation, shell/file access, and audio/video streaming.392 npmMIT