---
title: "Kuroko — MCP server to drive native macOS apps"
description: "Kuroko is a macOS MCP server that lets AI agents see and drive native apps via accessibility — in the background, no cursor takeover. 14-day free trial."
url: "https://klimakov.me/kuroko/"
---

黒子 · the stagehand the audience agrees not to see

# Let AI agents drive your Mac apps. Never your mouse.

Kuroko is an MCP server that lets AI agents see native macOS apps the way assistive tech does — the real accessibility tree, not pixels — and act on it in the background. No focus steal, no cursor hijack: the agent works backstage while you keep working.

[Download for macOS](https://github.com/olegklimakov/kuroko/releases/download/v1.0.3/Kuroko-1.0.3.dmg)[Connect an agent](https://klimakov.me/kuroko/#connect)

Developer ID–signed & notarized · 14-day free trial · up to 3 Macs

Cardsnot frontmost

New card

Fix onboarding copy

Ship the Q3 report

Actions are posted straight to the app's process — your real cursor never moves.

why not computer-use

## Backstage, not on stage

Screen-driving agents borrow your seat: they move the real cursor and read pixels. Kuroko stays out of the audience's view entirely.

### Pixel-driven automation

on stage

- sees

  Full-screen screenshots. Guesses what's a button from pixels.

- acts

  Moves your real cursor to coordinates and hopes the layout didn't shift.

- meanwhile

  Your Mac is occupied. You watch, or you wait.

- windows

  Must be frontmost and visible to be seen at all.

### Kuroko

backstage

- sees

  The app's accessibility tree — roles, labels, identifiers, frames.

- acts

  Semantic AX actions, falling back to events posted directly to the app's process.

- meanwhile

  You keep typing in another app. Focus never moves.

- windows

  Screenshots via ScreenCaptureKit — even fully occluded.

the surface an agent gets

## Thirteen tools, one protocol

Plain MCP over stdio — point Claude Code, Claude Desktop or any MCP host at the binary and the whole stage crew is available.

- `list_apps`running apps and their bundle ids
- `check_permissions`the server's own AX and recording status
- `get_ui_tree`the accessibility tree; outline mode for huge windows
- `screenshot`background PNG of one window, size-capped
- `tap`press an element by label, id or role
- `double_tap`double-click an element
- `input_text`type into an element; refuses password fields
- `press_key`⌘S, ⌘F, arrows — named keys with modifiers
- `scroll`bring off-screen elements into view
- `read_element`one element's fields, as JSON
- `assert_visible`wait for an element to appear
- `launch_app`start an app in the background
- `stop_app`quit or force-kill a running app

the trust model

## Assume the agent goes rogue

Handing an agent your open apps is a real grant of power — a prompt-injected agent is the realistic threat. Kuroko is built so that the grant is constrained, auditable and revocable.

- ### App policy

  Terminal, Keychain Access, 1Password and System Settings are denied by default. Flip to a strict allowlist when only one app should be drivable.

- ### Read-only switch

  "armWriteTools": false disarms tapping, typing, keys and app control in one move. The agent can look, not touch.

- ### Secure fields refused

  input\_text will not type into a password field. Not configurable — on purpose.

- ### Everything on the record

  Every call lands in a local JSONL action log the app tails live. Typed text is logged by length only; content never hits disk.

- ### Bounded by design

  Timeouts, tree depth and node budgets are clamped, so a hung target app can never freeze the server.

- ### No network surface

  stdio only — nothing listens on a port.

kuroko.app

## A companion you can watch

The app never drives anything itself — it exists so you can set Kuroko up and then see exactly what agents are doing with it.

- **Onboarding** walks through Accessibility and Screen Recording once.
- **Overview** shows permissions, connection and license status at a glance.
- **Activity Log** tails every agent action live — tool, target, duration, errors.
- **Connect** holds copy-paste instructions for any MCP host.
- A **menu-bar** glyph keeps status one click away after you close the window.

setup

## Connect in a minute

1. ### Grant permissions

   Accessibility goes to the process that launches the server — your terminal or agent host. Screen Recording is needed only for the `screenshot` tool.

2. ### Add the server

   Claude Code:

   ```
   claude mcp add kuroko -- /path/to/kuroko mcp
   ```

   Claude Desktop — or any other MCP host:

   ```
   {
     "mcpServers": {
       "kuroko": { "command": "/path/to/kuroko", "args": ["mcp"] }
     }
   }
   ```

3. ### Ask for something real

   “Open the git client, tap the commit ‘Improve error messages’, and confirm the detail panel shows its author and date.”

licensing

## Simple licensing

**14-day trial** with everything enabled — no account, no card.

**One license, up to 3 Macs.** Activate online in seconds; deactivate a device to move a seat.

**Notarized direct download.** The App Store sandbox forbids driving other apps, so Kuroko doesn't live there.

[Download for macOS](https://github.com/olegklimakov/kuroko/releases/download/v1.0.3/Kuroko-1.0.3.dmg)[See pricing](https://klimakov.me/kuroko/buy/)