Happy slice of mcp pizzaMCP.pizza

Peekaboo

MCP.Pizza Chef: openclaw

This tool gives your AI assistant eyes and hands on your Mac: it can capture a picture of your whole screen or a single app window, read what's currently on screen as an organized list of buttons and text, and then click, type, or navigate menus for you. It connects to Cursor and other compatible apps such as Claude Code, and installs with one command using npx — no extra account or password is required to get started, though the optional automated 'agent' mode needs a connected AI model.

Coding
Other
Web/Research

Use This MCP server To

Take a screenshot of any app or my entire screen See exactly what's on my screen as a readable list Click a button or link inside an app for me Type text into a website or app automatically Open a browser, search a site, and click the results Automate a multi-step task on my Mac hands-free

README

Peekaboo 🫣 — Mac automation that sees the screen and does the clicks.

CI npm GitHub release macOS 15+ Swift 6.2 Node License Homebrew Ask DeepWiki

Peekaboo is a macOS CLI and menu-bar app for screen capture, accessibility inspection, and native UI automation. Use it directly, let its agent plan multi-step work, or expose the same toolset to MCP clients.

Peekaboo banner

Install

The released CLI and app require macOS 15 or later.

CLI with Homebrew

brew install steipete/tap/peekaboo

MCP package with npm

The npm package requires Node.js 22 or later and includes the CLI plus its MCP launcher.

npx -y @steipete/peekaboo --version

See MCP setup to connect it to Codex, Claude Code, Cursor, or another MCP client.

Mac app

Download the signed DMG from the latest GitHub release. The menu-bar app provides permission onboarding, visual feedback, and agent sessions; install the CLI separately when you also need peekaboo on PATH.

For source builds and alternative install details, see the installation guide.

Quick start

Check the permissions available to Peekaboo, then take a screenshot:

peekaboo permissions status
peekaboo image --mode screen --path /tmp/peekaboo-screen.png

Screen capture requires Screen Recording permission. Accessibility permission enables UI inspection and control; the permissions guide covers setup and the additional permission used for synthetic input.

Inspect a running app to get a structured UI map with opaque element IDs:

peekaboo see --app Finder --json

That is the core loop: observe the current screen, choose an element from the result, and act on it.

Automate an app

Target an element by its accessible label, then send text to the same app:

peekaboo click "Address and search bar" --app Safari
peekaboo type "github.com/openclaw/Peekaboo" --app Safari --return

Targeted input uses background delivery when Peekaboo can resolve the process, so the app does not have to become frontmost. Add --foreground when an app only accepts input in its focused key window. See the automation guide for element IDs, coordinates, snapshots, waits, and input behavior.

Agent and MCP

The agent combines the same observation and action tools into a natural-language run:

peekaboo agent "Open Safari, go to github.com, and search for Peekaboo"

Agent runs need a configured model provider. See agent setup for providers and sessions, or MCP setup to expose Peekaboo's tools to another client.

Command map

Goal Commands Guide
Observe the desktop image, see, list, screen Capture and inspection
Interact with UI click, type, press, scroll, drag, set-value, perform-action Automation
Control macOS app, window, menu, menubar, dock, dialog, space Command reference
Run workflows agent, run Agent · Scripts
Integrate with clients mcp, browser, tools MCP

Run peekaboo help <command> for live CLI help. The complete command index links to flags, examples, and troubleshooting for every command.

Configuration

Peekaboo stores provider credentials and settings under ~/.peekaboo. Use peekaboo config to inspect or change them, and consult the configuration guide for profiles, environment variables, and custom providers. The provider reference covers hosted, compatible, and local model backends.

Shell completions for zsh, bash, and fish come from peekaboo completions; see the completion guide for persistent setup.

Learn more

  • Project direction
  • Platform support
  • Architecture
  • Building from source
  • Testing
  • Agent chat loop
  • Service API

Community

  • PeekabooWin — Windows-first rewrite of the Peekaboo automation loop (JavaScript + PowerShell) by @FelixKruger
  • PeekabooX — Linux-first rewrite of the Peekaboo automation loop (Rust + Python) by @nordbyte

Development

Source builds require macOS 15 or later, Swift 6.2 or later, Node.js 22 or later, and the repository's submodules.

pnpm install --frozen-lockfile
pnpm run build:cli
pnpm run lint:docs
pnpm run test:safe

More build, signing, and test details live in docs/building.md.

License

MIT. See LICENSE.

Peekaboo FAQ

Can I use this to take a screenshot of a specific app?
Yes — you can ask your AI assistant to capture just one app's window or your entire screen and save the image.
Can I use this to have my AI click buttons and fill out forms on my Mac?
Yes — it can find buttons, links, and text fields inside an app and interact with them the same way you would with a mouse and keyboard.
Which apps can I use this with?
It's built for Cursor and other AI apps that support the same connection standard, such as Claude Code; check your app's settings to confirm it's supported.
Do I need an account or a paid key to use it?
No — the basic screen-capture and clicking features work without signing up for anything; only the optional automated 'agent' mode needs you to connect an AI model like Claude, GPT, or Gemini.
How hard is it to set up?
You install it with one command and then add a short snippet to your AI app's settings; no coding or building from source is required.
Does this work on Windows or Linux?
No — it's built specifically for Mac computers running a fairly recent version of macOS; separate community projects exist for Windows and Linux.
Will it need special permission from my Mac?
Yes — macOS will ask you to grant Screen Recording permission for screenshots, and Accessibility permission if you want it to click and type for you.
Can it tell me what's shown on my screen?
Yes — it can look at what's currently displayed and answer questions about it using a connected AI model, so you could ask what an error message says or what's inside a window.