Skip to main content
Glama

Karagöz

npm version CI License: MIT Node.js npm downloads Glama score

Website · Docs

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-stop on an app that is not installed says nothing, simctl and devicectl report 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 returns APP_NOT_FOUND. A refused install is INSTALL_FAILED with the platform's own code in reason, 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-tree before 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 mcp exits 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 --timeout waits 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: adb from 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, text and key need 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-tree and the input commands also need a USB cable, UI Automation on, and karagoz's runner, which install-runner installs.

What each command needs, and how karagoz finds adb and Xcode.

Install

npm install -g karagoz-mcp
karagoz devices

Or 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.

An iOS simulator next to a list of tool calls. Asked to open Settings on the iOS simulator and turn on dark mode, Claude Code calls devices, launch, ui_tree, tap on the Appearance row by id, ui_tree, tap on Dark by text, and ui_tree, and the simulator switches to dark mode.


MCP server

karagoz mcp

Starts 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 mcp

Claude Desktop

Download karagoz.mcpb from the latest release and open it. Desktop installs it as an extension.

Cursor

Add to 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 mcp

Then 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 = 600

Other ways to register each client, running from a clone, and the tools' arguments, results and behavior.

Agent 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 instructions

410

All 18 definitions, loaded by one ToolSearch call

3,634

Every session, tool search off (ENABLE_TOOL_SEARCH=false): every definition and instructions

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.com into the email field and tap Continue."

  • "Open myapp://orders/42 on 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

devices

List connected devices

screenshot

Save a full-resolution PNG and return its path with scale metadata

ui-tree

Return the accessibility tree of the focused window

tap

Tap a point, or a node found by text or id

long-press

Press and hold a point or a node

double-tap

Tap a point or a node twice

swipe

Swipe between two points

text

Type text into the focused field

key

Press a key

install

Install or replace an app

launch

Start an app as its launcher icon does

open-url

Open a URL or deep link in the app that handles it

terminate

Stop every process of an app

uninstall

Remove an app

logs

Read the device log

doctor

Report which adb and Xcode karagoz uses

install-runner

Build karagoz's runner and install it on an iPhone

uninstall-runner

Remove karagoz's runner from an iPhone or a simulator

mcp

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

adb screencap

uiautomator dump

input; text outside ASCII and double-tap through a helper copied to the device for the call

adb install, am, pm, cmd package

logcat

iOS simulator

simctl io screenshot

karagoz's Swift helper, compiled on first use with Xcode's swiftc

The helper: the simulator's input service, and XCUIAutomation for text (Xcode 27). On a Mac that never had Xcode 27, karagoz's runner inside the simulator

simctl

log show inside the simulator

iPhone

devicectl

karagoz's runner, an XCUITest bundle that xcodebuild starts and karagoz reaches over USB

karagoz's runner

devicectl

The phone's log relay over USB, read with macOS's log


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 tools
devicesList devicesA
Read-only

List Android devices and emulators, running iOS simulators, and iPhones connected to this Mac.

Inputs: no named parameters.

doctorCheck adb and XcodeA
Read-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 appA
Destructive

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 logsA
Read-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 treeA
Read-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 appC
Destructive

Remove an app.

Inputs: package (required), device.

uninstall_runnerRemove karagoz's iPhone runnerB
Destructive

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

    B3.4/5.0

    Scored across 18 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables 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.
      9
      61 PyPI
      2
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      39
      45,799 npm
      Apache 2.0
    • A
      license
      C
      quality
      B
      maintenance
      Enables 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.
      94
      9 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT