Peekaboo

Peekaboo is an MCP server and macOS utility that enables AI agents to capture screen images, inspect accessibility trees, and perform native user interface automation. It connects LLM-driven environments like Cursor, Claude Code, and Codex directly to macOS window management and accessibility APIs. Developers and automated agents use Peekaboo to observe active screen elements, target specific application windows, and simulate native user inputs without requiring third-party testing frameworks. By translating user interfaces into structured JSON UI maps, it allows models to identify opaque element identifiers and trigger actions such as clicking buttons, typing text, scrolling, and navigating system menus. Peekaboo also supports background input delivery when processes can be cleanly resolved, avoiding interruptions by not forcing target applications to stay frontmost. The server provides deep system integration, supporting permissions checks, multi-display captures, Dock interactions, and custom dialog management under modern macOS versions.

Category: Design, Media & Creative

Tags: automation, image-capture, macos, screenshot

Visit Peekaboo

How to install and configure Peekaboo

1. Ensure your system runs macOS 15 or later with Node.js 22 or later installed. 2. Install Peekaboo via Homebrew by running brew install openclaw/tap/peekaboo or run the npm launcher directly using npx -y @steipete/peekaboo. 3. Grant the required macOS system permissions by checking status with peekaboo permissions status and allowing Screen Recording and Accessibility in System Settings. 4. Connect Peekaboo to your MCP client (such as Cursor, Codex, or Claude Code) by adding the Peekaboo execution command (peekaboo mcp or through the npm package runner) to your client configuration file as described in the Peekaboo repository. 5. Restart your MCP client to initialize the server tools.

What you can do with Peekaboo

• Capturing screenshots of entire displays or targeted application windows directly from an AI client session. - Inspecting structured accessibility trees to identify UI element IDs, text values, and window hierarchies in running macOS apps. - Automating repetitive GUI tasks like opening Safari, navigating to specific URLs, and submitting web searches in the background. - Triggering menu bar items, system dialog confirmations, and dock interactions using automated semantic click and press commands. - Allowing autonomous coding agents to verify local app rendering and visually inspect native software during development cycles.

Key facts

• Open Source
• https://github.com/steipete/Peekaboo
• Design, Media & Creative, Developer Tools & Code Intelligence
• automation, image-capture, macos, screenshot

Part of MCP Servers

What is Peekaboo?

Peekaboo is an open-source macOS automation tool and MCP server. It gives AI agents the ability to capture desktop screenshots, inspect running software through macOS accessibility APIs, and perform native keyboard and mouse actions.

What are the system requirements for Peekaboo?

Peekaboo requires macOS 15 or later. If you run the MCP launcher using the npm package, it also requires Node.js version 22 or later. Compiling from source requires Swift 6.2 or later.

How do I install Peekaboo?

You can install Peekaboo on macOS using Homebrew with brew install openclaw/tap/peekaboo, download the signed DMG release from GitHub, or execute the package directly using npx -y @steipete/peekaboo.

Which MCP clients work with Peekaboo?

Peekaboo works with MCP-compatible clients such as Codex, Claude Code, Cursor, and other tools configured to communicate with local Model Context Protocol command-line servers.

What permissions are required to run Peekaboo?

Peekaboo requires macOS Screen Recording permissions to capture displays and windows. It also requires Accessibility permissions to inspect user interface element trees and simulate synthetic input actions such as clicks and keystrokes.

Is Peekaboo open source?

Yes, Peekaboo is open-source software released under the MIT license on GitHub, allowing free usage, inspection, and modification.