Peekaboo
macOS screen capture, AI visual analysis, and full GUI automation for AI agents.
Add to your client
Copy the config for your MCP client and paste it into its config file.
npx -y @steipete/peekabooPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"peekaboo": {
"command": "npx",
"args": [
"-y",
"@steipete/peekaboo"
],
"env": {
"PEEKABOO_AI_PROVIDERS": "openai/gpt-5.5,anthropic/claude-opus-4-8"
}
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- macOS 15.0+ (Sequoia)
- Node.js 22+ (for the npm MCP wrapper)
- Screen Recording permission
- Accessibility permission
- Event Synthesizing permission (for keyboard/coordinate input)
- AI provider API key for hosted visual analysis (optional)
About Peekaboo
Peekaboo brings high-fidelity screen capture, AI analysis, and complete GUI automation to macOS. It runs as a native CLI and as an optional MCP server exposing the same tools to MCP clients such as Codex, Claude Code, and Cursor. Beyond screenshots, it offers action-first UI automation (click/type/scroll/hotkey/menu/window/app/dock/space), direct accessibility tools (set-value, perform-action), and a natural-language agent that chains tools for multi-step workflows. Background, process-targeted input lets it interact with apps without stealing focus.
Tools & capabilities (28)
seeCapture and annotate the current UI, returning a snapshot plus opaque element IDs.
clickClick an element by ID, label/query, or coordinates, with optional wait and foreground delivery.
typeEnter text with pacing/clear/profile options into the targeted app.
set-valueDirectly set a settable accessibility value on an element.
perform-actionInvoke a named accessibility action (e.g. AXPress) on an element.
pressSend special keys and key sequences with count/delay/hold options.
hotkeySend modifier combos such as cmd/ctrl/alt/shift chords.
pastePaste text/file/image payloads with clipboard restore.
scrollScroll views or a specific element in a given direction/amount.
swipePerform smooth gesture-style drags between points.
dragDrag-and-drop between elements or coordinates, including Dock/Trash targets.
moveMove the cursor to an element or coordinates without clicking.
windowList, move, resize, focus, and set bounds of windows across Spaces.
appLaunch, quit, relaunch, switch, and list applications.
spaceList or switch macOS Spaces and move windows between them.
menuList and click app menus and menu extras.
menubarList and click status-bar items by name or index.
dockLaunch, right-click, hide, show, and list Dock items.
dialogDrive system dialogs (open/save/input/file/dismiss).
imageScreenshot screen, window, or menu bar with Retina scaling and optional AI analysis.
listEnumerate apps, windows, screens, menubar items, and permissions.
toolsInspect the native Peekaboo tools available.
agentRun natural-language multi-step automation across Peekaboo tools.
runExecute a .peekaboo.json automation script.
sleepInsert millisecond delays between automation steps.
cleanPrune snapshots and caches.
permissionsCheck and grant required macOS permissions.
configManage credentials, providers, and settings.
What this server can do
Peekaboo provides tools for these capabilities — tap one to see every MCP server that does the same:
When to use it
- Let an AI agent take screenshots of an app or the whole system and answer visual questions about what is on screen.
- Automate routine macOS GUI tasks (clicking buttons, filling text fields, navigating menus) without stealing focus.
- Drive multi-step desktop workflows from natural language, e.g. 'Open Notes and create a TODO list with three items'.
- Capture pixel-accurate Retina screenshots of windows, screens, or the menu bar for documentation or QA.
- Build reproducible, testable UI automation scripts via .peekaboo.json.
Security notes
Requires macOS Screen Recording and Accessibility permissions (and Event Synthesizing for keyboard/coordinate input). The server can capture the entire screen and fully control the GUI (clicks, typing, app/window/menu actions), so it has broad access to the user's desktop. AI provider API keys are supplied via PEEKABOO_AI_PROVIDERS / config; no key is needed for capture/automation alone but is required for AI analysis with hosted providers.
Peekaboo FAQ
Which platforms are supported?
Peekaboo targets macOS 15.0+ (Sequoia). Community rewrites exist for Windows (PeekabooWin) and Linux (PeekabooX), but the main project is macOS-only.
Do I need an AI API key to use it?
No. Screen capture and GUI automation work without any AI key. An AI provider key (set via PEEKABOO_AI_PROVIDERS or peekaboo config add) is only needed for AI visual analysis with hosted providers; local models via Ollama/LM Studio are also supported.
What permissions does it require?
macOS Screen Recording and Accessibility permissions are required, plus Event Synthesizing for keyboard and coordinate-based input. Run 'peekaboo permissions request-event-synthesizing' if it reports as missing.
Which MCP clients are supported?
The README lists Codex, Claude Code, and Cursor, using the npx -y @steipete/peekaboo command in an mcpServers config block.
Alternatives to Peekaboo
Compare all alternatives →
Automate your existing browser with AI using your real profile, logged-in sessions, and stealth fingerprint.
All-in-one web access MCP — Web Unlocker, SERP, Scraper API, and a cloud Scraping Browser.
Popular community Playwright + API testing MCP server with codegen, screenshots, and device emulation.