Peekaboo

Name: Peekaboo
Author: openclaw

macOS screen capture, UI inspection and native click-and-type automation exposed over MCP

By openclaw Swift Local · stdio Browser automation AI and ML

GitHub npm Website

80 popularity score ★ 5.4k ↓ 1.5k/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal

claude mcp add peekaboo -- npx -y @steipete/peekaboo mcp

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/peekaboo",
        "mcp"
      ]
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/peekaboo",
        "mcp"
      ]
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "peekaboo": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@steipete/peekaboo",
        "mcp"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.peekaboo]
command = "npx"
args = ["-y", "@steipete/peekaboo", "mcp"]

Gemini CLITerminal

gemini mcp add --scope user peekaboo npx -- -y @steipete/peekaboo mcp

Settings 12

Set together: providers
`PEEKABOO_AI_PROVIDERS`	Optional: Comma-separated provider/model list for analyze and agent. Default `openai/gpt-5.6,anthropic/claude-opus-5`. For analyze, agent.
`OPENAI_API_KEY` secret	Optional: OpenAI key for GPT models. For analyze, agent.
`ANTHROPIC_API_KEY` secret	Optional: Anthropic key for Claude models. For analyze, agent.
`X_AI_API_KEY` secret	Optional: xAI key for Grok models; XAI_API_KEY and GROK_API_KEY are also read. For analyze, agent.
`GEMINI_API_KEY` secret	Optional: Gemini key; GOOGLE_API_KEY is also read. For analyze, agent.
`OPENROUTER_API_KEY` secret	Optional: OpenRouter key. For analyze, agent.
`PEEKABOO_OLLAMA_BASE_URL`	Optional: Native Ollama server base, without /v1; OLLAMA_BASE_URL is also read. Default `http://localhost:11434`. For analyze, agent.
`PEEKABOO_ALLOW_TOOLS`	Optional: Allowlist of tools the server exposes.
`PEEKABOO_DISABLE_TOOLS`	Optional: Tools to hide, e.g. browser for a native-only catalog.
`PEEKABOO_INPUT_STRATEGY`	Optional: Input strategy: actionFirst, actionOnly, synthFirst or synthOnly; the synth ones hide set_value and action.
`PEEKABOO_DEFAULT_SAVE_PATH`	Optional: Folder where screenshots are saved. Default `~/Desktop`. For image.
`PEEKABOO_LOG_LEVEL`	Optional: debug, info, warn or error. Default `info`.

What it does

Peekaboo is a Mac command-line tool and menu-bar app that takes screenshots, reads the accessibility tree of running apps and acts on what it finds. Running `peekaboo mcp` starts it as a stdio MCP server that offers the same toolset to clients such as Claude Code, Codex or Cursor.

The usual loop is to call `see` on a screen, app or exact window, get back a snapshot with element IDs, then pass those IDs to `click`, `type`, `press`, `scroll`, `set_value` or `action`. Other tools list and manage apps, windows, menus, the Dock, dialogs and Spaces, record bounded screen or window captures, read the clipboard and control a Chrome browser child. The tool catalog in the v4.9.6 source registers 27 tools; which of them a client sees depends on the authority mode, the input strategy and the PEEKABOO_ALLOW_TOOLS and PEEKABOO_DISABLE_TOOLS filters.

The `analyze` tool and the nested `agent` tool send images or tasks to a model provider you configure. The MCP docs name OpenAI, Anthropic, xAI and a local Ollama server; the configuration code also reads keys for Gemini, MiniMax, Moonshot/Kimi and OpenRouter. When PEEKABOO_AI_PROVIDERS is unset, the code falls back to openai/gpt-5.6,anthropic/claude-opus-5. Everything else runs on the Mac itself.

By default the MCP server is background-only: input goes to an exact resolved app or window without bringing it to the front. Foreground actions, browser connection and persistent clipboard writes are refused unless the person starting the server passes `--allow-foreground`. Rich paste needs `--allow-temporary-clipboard` instead.

What it needs

Runtime	Node.js 22+
Runs on	macOS
Also	macOS Screen Recording permission macOS Accessibility permission A model provider key or Ollama server for analyze and agent

The npm package needs Node.js 22 or later. Grant Screen Recording for capture and Accessibility for inspection and control; synthetic background keyboard input also uses the Event Synthesizing permission. Only analyze and the nested agent need a provider: set OPENAI_API_KEY, ANTHROPIC_API_KEY or X_AI_API_KEY, or run Ollama. Keys can also be stored with `peekaboo config` under ~/.peekaboo.

Limits

Platform Runs on macOS 15 or later only.
Not covered Only the stdio transport works; the http and sse names and --port are reserved and currently fail with an error.
Not covered Background-only by default: focusing apps, foreground key chords, browser connect and clipboard set, clear or restore need --allow-foreground.
Size cap analyze accepts only existing .png, .jpg, .jpeg and .webp files.
Size cap Temporary rich paste (with --allow-temporary-clipboard) is limited to 10 MB for the payload and its companion.
Not covered set_value and action are hidden when the input strategy is synthFirst or synthOnly.
Not covered menu covers only application-menu list and click; menu-bar status items are not reached through it.
Cost analyze and agent call the configured model provider, which bills by its own pricing unless a local Ollama server is used.

Runs on macOS only; Windows and Linux rewrites are separate community projects. Only the stdio transport works: the http and sse flags exist but those transports are not implemented. In the default background-only mode, focusing or switching apps, foreground key chords, browser page actions and clipboard set, clear or restore are hidden or refused. `analyze` accepts only .png, .jpg, .jpeg and .webp files. Temporary rich paste is capped at 10 MB. `set_value` and `action` are hidden when the input strategy is synthetic-only.

Who it suits

Suits people on a Mac who want an assistant to look at the screen and operate native apps through accessibility, not only a web page. It is local software with no account of its own; only analyze and agent reach a model vendor, and Ollama keeps those local too. Because it can click, type and paste into any app the user can reach, it fits a supervised desktop session better than an unattended one, and the background-only default keeps it from taking focus unless a person allows it. Anyone on Windows or Linux, or who needs a remote HTTP server, should look elsewhere.

Tools 27

6 only read, 21 change things.

image changes: Take a plain screenshot of the screen, an app or a window and save or return it
capture changes: Record a bounded live screen, window or region capture, or ingest a video, into frames and optional MP4
analyze: Ask a configured model provider a question about an existing image file
browser changes: Work with a scoped Chrome browser child that the server owns
permissions: Report which macOS permissions the host currently has
sleep: Wait for a set time between steps
see: Capture a target and return detected UI elements with IDs and a snapshot reference
inspect_ui: Read the accessibility structure of an app or window in detail
verify_state: Check that the UI is in an expected state after an action
click changes: Click an element by ID, by query or at coordinates
type changes: Type text into a target app or element
set_value changes: Set the accessibility value of a settable field or control directly
select_text changes: Select text or place the caret without changing the field's content
action changes: Invoke a named accessibility action such as AXPress on an element
scroll changes: Scroll an element or a point in an exact window
press changes: Press keys or key chords
drag changes: Drag from one point or element to another
move changes: Move the pointer
app changes: List running apps and launch, quit or otherwise manage them
window changes: List windows with IDs and bounds and manage them
menu changes: List and click items in an app's menu bar menus
clipboard changes: Read or save clipboard contents; changing it needs foreground authority
paste changes: Paste text into an exact authorised app or window
agent changes: Hand a natural-language task to Peekaboo's own background-only agent
dock changes: Work with Dock items
dialog changes: Handle system and app dialogs
space changes: List and work with macOS Spaces

Popularity

80 popularity score, on our list (the bar is 36)

★ 5.4k ↓ 1.5k/wk

GitHub stars	5,447	44.8 points
Stars in 30 days	+188	10 points
npm downloads, last week	1,541	25.5 points

Measured 2026-11-07. How the score works.

Where it is published

Code	openclaw/peekaboo ★ 5.4k
npm	@steipete/peekaboo 4.9.8, 2026-11-05

What it can reach

Runs	On your machine
Reaches	Files on your machine, Drives a browser, The internet
Changes things	Yes: it can write, send, create or delete
Sign-in	None
Licence	MIT (npm)
Last code change	2026-11-07

Runs locally on the Mac and, once granted Screen Recording and Accessibility permission, can see anything on screen and click, type, paste and drag in any app the user can reach. It writes screenshots, recordings and metadata files to disk. Images and tasks given to analyze or agent go to the configured provider (OpenAI, Anthropic or xAI) unless a local Ollama server is used. The MCP server is background-only by default: foreground input, browser connection and persistent clipboard changes need the person launching it to pass --allow-foreground, and tool arguments cannot grant that. The nested agent never gets shell access. Provider keys and settings are stored under ~/.peekaboo.

Over time

GitHub stars 5.4k +188 (+4 %)

5.4k5.3k

7 Oct 20267 Nov 2026

npm downloads a week 1.5k +1.4k (+1522 %)

3.2k19

1 Dec 20257 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 80 +9 (+12 %)

8166

7 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-23.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![Peekaboo on EveryMCPServer](https://everymcpserver.com/badge/peekaboo.svg)](https://everymcpserver.com/servers/peekaboo)

Connect your client

Add in one click

Or add it by command or config

Settings 12

What it does

What it needs

Limits

Who it suits

Tools 27

Similar servers

Browser Use

Open Computer Use

Skyvern

Clawd Cursor

flow-mcp

computer-use-linux