Skip to content
MCP server

Karagöz

Drive Android and iOS devices and emulators from a CLI or an AI agent, no daemon

Runs locallyStatus and history
Pricing
Open source
Platforms
CLI, Android, iOS
Runs
Locally
Version
0.4.0
Listing updated
3 days ago

About Karagöz

Karagöz is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

Karagöz reads the screen as text. The ui-tree command prints each element with its bounds in pixels, and tap --text finds an element by label and taps the centre of its box. Every command returns one line of JSON, and failures come back as codes such as ELEMENT_NOT_FOUND, APP_NOT_FOUND or INSTALL_FAILED with the platform's own code in a reason field, where adb, simctl and devicectl often stay silent or bury the error in text.

One command set covers four targets: Android emulators, Android phones, iOS simulators and iPhones. Screenshots are saved to disk and returned as a path with pixel size and scale, so the agent prefers the cheaper accessibility tree. Each command exits when it answers, and karagoz mcp exits with its client. On iPhones and some simulators, a small runner is installed and stops 10 minutes after last use.

It needs Node 22+, plus adb for Android or Xcode on a Mac for iOS. The README calls it a primitive layer rather than a test framework, with no assertions, flows or reports, and describes it as early development.

Install

Run in a terminal

claude mcp add karagoz-mcp -- npx -y karagoz-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "karagoz-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "karagoz-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "karagoz-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "karagoz-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "karagoz-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "karagoz-mcp"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "karagoz-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "karagoz-mcp"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "karagoz-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "karagoz-mcp"
      ]
    }
  }
}

What it does

Screen as text
ui-tree lists every element with its pixel bounds.
Tap by label
tap --text finds an element and taps the centre of its box.
Coded errors
Failures return codes like APP_NOT_FOUND or INSTALL_FAILED with the platform reason.
Four targets, one contract
Same commands on Android emulators and phones, iOS simulators and iPhones.
No resident daemon
Commands exit after answering, and the runner stops after 10 idle minutes.
CLI and MCP
The MCP server returns the CLI's JSON line unchanged.

Good for

  • Let an agent tap through a mobile app flow
  • Install an app and read why an install failed
  • Capture a screenshot with size and scale for design comparison
  • Run the same steps on an Android emulator and an iOS simulator

Pricing

Open source

MIT licence, free on npm

Prices change. Check karagozmcp.com before you buy.

Karagöz FAQ

What do I need to run it?

Node 22 or newer, plus adb for Android or Xcode on a Mac for iOS.

Is it a test framework?

No. The README says it is a primitive layer with no assertions, runner or reports.

Does it leave a daemon running?

No. Commands exit when done; only the runner stays up, stopping 10 minutes after last use.

What is the licence?

MIT, published on npm as karagoz-mcp.

Is Karagöz free?

Yes. Karagöz is open source, so you can use and self-host it for free.

How do I add Karagöz to Claude Code?

Run this command in your terminal: claude mcp add karagoz-mcp -- npx -y karagoz-mcp

What are the best alternatives to Karagöz?

The closest alternatives to Karagöz are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to Karagöz

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools