Peekaboo

Screenshots of any Mac app or screen, with optional questions about what is on it.

Needs your setup first
★ 5.4K GitHub stars
Last commit 26 Oct 2026

At a glance

Peekaboo gives an agent eyes on macOS. It can capture a single window, an app or the full screen, and it can pass the image to a vision model to answer a question such as "is the error dialog still showing?"

It is a CLI as well as an MCP server, written by Peter Steinberger, and it needs the usual macOS Screen Recording permission the first time.

Made by: Peter Steinberger and the OpenClaw contributors
Licence: MIT
Latest version: 2.0.3 (3 Jul 2025)
npm package: @steipete/peekaboo-mcp
GitHub stars: 5.4K
Last commit: 26 Oct 2026
Tools: 3
Runs on: Your computer

Our check: It needs something our Linux test machine does not have (an account, a desktop app, a Mac or a running service), so on 26 Oct 2026 we listed its tools from its package instead of running this config.

What's in the pod: its tools

We found 3 tools when we ran its package, before any sign-in or app was connected, on 26 Oct 2026. 1 only read. The rest can change things, so keep your app's "ask before each tool call" setting on for them.

How we tested it: Listed by the server code in the npm package, run on Linux. npm refuses to install it outside macOS, and the tools themselves need a Mac.

Changes things2 tools · Can create, edit, send or delete.

Tool	What it is for
`analyze`	Asks an AI vision model a question about an image file you already have.
`image`	Captures the whole screen, one app or one window, and can describe what it sees.

Only reads1 tool · Looks things up and changes nothing.

Tool	What it is for
`list`	Lists running apps, their windows, or Peekaboo's own status.

Tool groups

Look at the screen: see, screen list and window list: screenshots plus a map of every button and field with ids the agent can act on.
Work the interface: click, type, press, scroll, drag, set-value and action, aimed at a named element rather than guessed coordinates.
Control macOS: app, window, menu, menubar, dock, dialog and space: launch apps, move windows, pick menu items and switch desktops.
Run workflows: agent and capture: hand over a whole task in plain English, or record the screen.

Grouped and described by us. The README on GitHub lists the inputs each tool takes.

Set it up

Pick your app for the exact snippet and where it goes.

Where it goes: claude_desktop_config.json (Settings → Developer → Edit Config)

Claude Desktop

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

Where it goes: Your terminal, in the project folder

Claude Code

claude mcp add-json peekaboo '{"command":"npx","args":["-y","@steipete/peekaboo-mcp"]}'

Where it goes: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

Cursor

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

Where it goes: .vscode/mcp.json in your project

VS Code

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

Where it goes: ~/.codeium/windsurf/mcp_config.json

Windsurf

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

New to this? See the setup guides for Claude Code, Cursor, Claude Desktop and ChatGPT.

Settings

Names are exactly as the project spells them. Required ones are marked.

Setting	What it does
`npx -y @steipete/peekaboo`Config · required	The npm package bundles the CLI and the MCP launcher your client starts. Needs Node.js 22 or later.
`Screen Recording permission`Config · required	Needed for any screenshot. Grant it in System Settings, Privacy & Security.
`Accessibility permission`Config · required	Needed to read the interface and to click or type.
`~/.peekaboo`Config	Where settings and AI provider keys for the built-in agent are stored. Change them with peekaboo config.
`--allow-foreground`Command line flag	Lets an agent run bring apps to the front. Without it, Peekaboo only sends input in the background where it can.

What it can touch

It can read

Everything visible on your Mac's screen, and the interface of any running app

It can change

Clicks, types and presses keys in your apps as if you did it
Opens, closes and moves apps and windows

Safer setup: Grant permissions only to the Peekaboo app or terminal you use, and pin actions to one window id so input cannot land in the wrong app.

Before you start

macOS
Screen Recording permission for the app running it
Node.js 18 or newer

If it does not work

Screenshots are black or fail: Screen Recording permission is missing. Run peekaboo permissions status to see what is granted, then add it in System Settings.
Clicks and typing do nothing: Grant Accessibility permission, and check the target app is not showing a modal dialog.
Input goes to the wrong window: List windows with peekaboo window list, then pass --window-id to every action.

Peas in a pod: similar servers

How Peekaboo lines up against other developer tools servers on the shelf.

Server	Tools	Runs on	Licence	Stars
Peekaboo	3	Your computer	MIT	5.4K
Kubernetes MCP Server	14	Your computer	Apache-2.0	2.2K
IDA Pro MCP	48	Your computer	–	13.2K
Desktop Commander	25	Your computer	MIT	10.1K
Serena	3	Your computer	–	30.7K