# Karagöz

> Karagöz is an open-source MCP server for developer tools. Drive Android and iOS devices and emulators from a CLI or an AI agent, no daemon. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, Android, iOS, macOS
- **Website:** https://karagozmcp.com
- **Repository:** https://github.com/yagizdo/karagoz-mcp/tree/HEAD/packages/karagoz
- **MCP Registry name:** io.github.yagizdo/karagoz-mcp
- **Categories:** developer tools
- **Listing updated:** 2026-11-14

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add karagoz-mcp -- npx -y karagoz-mcp
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## 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

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/karagoz
