The Peekaboo MCP server provides macOS screen capture and AI-powered image analysis for integration with AI assistants like Claude Desktop and Cursor IDE.
Capture Screenshots: Take screenshots of entire screens, specific app windows, or all windows of an app, with control over output format (file or Base64 data).
AI Image Analysis: Analyze captured or existing images using AI models like GPT-4 Vision, Claude, or local models via Ollama.
System Information: List running applications, their open windows (including details like position, size, and IDs), and server status.
Integration: Seamlessly integrate with AI assistants for visual context and debugging workflows.
Privacy Options: Support for local AI analysis through Ollama for privacy-focused use cases.
Advanced Targeting: Fuzzy matching and precise targeting for apps, windows, and screens.
Enables comprehensive screen capture capabilities on macOS, including capturing entire screens, specific application windows, or all windows of an app with various formatting options.
Enables local AI image analysis of screenshots through Ollama, supporting models like LLaVA and Qwen2-VL for vision tasks without sending data to the cloud.
Provides integration with OpenAI's vision models (like GPT-4o) for analyzing captured screenshots through the OpenAI API.
Peekaboo 🫣 - Mac automation that sees the screen and does the clicks.
Peekaboo brings high-fidelity screen capture, AI analysis, and complete GUI automation to macOS. Version 3 adds native agent flows and multi-screen automation across the CLI and MCP server.
Note: v3 is currently in beta (3.0.0-beta1) and has a few known issues; see the changelog for details.
What you get
Pixel-accurate captures (windows, screens, menu bar) with optional Retina 2x scaling.
Natural-language agent that chains Peekaboo tools (see, click, type, scroll, hotkey, menu, window, app, dock, space).
Menu and menubar discovery with structured JSON; no clicks required.
Multi-provider AI: GPT-5.1 family, Claude 4.x, Grok 4-fast (vision), Gemini 2.5, and local Ollama models.
MCP server for Claude Desktop and Cursor plus a native CLI; the same tools in both.
Configurable, testable workflows with reproducible sessions and strict typing.
Requires macOS Screen Recording + Accessibility permissions (see docs/permissions.md).
Related MCP server: Safari Screenshot MCP Server
Install
macOS app + CLI (Homebrew):
brew install steipete/tap/peekabooMCP server (Node 22+, no global install needed):
npx -y @steipete/peekaboo
Quick start
Command | Key flags / subcommands | What it does |
,
,
,
| Capture and annotate UI, return session + element IDs | |
,
,
, coords | Click by element ID, label, or coordinates | |
,
,
| Enter text with pacing options | |
key names,
| Special keys and sequences | |
combos like
| Modifier combos (cmd/ctrl/alt/shift) | |
,
,
| Scroll views or elements | |
,
,
| Smooth gesture-style drags | |
, modifiers, Dock/Trash targets | Drag-and-drop between elements/coords | |
,
| Position the cursor without clicking | |
,
,
,
,
| Move/resize/focus windows and Spaces | |
,
,
,
,
| Launch, quit, relaunch, switch apps | |
,
,
| List or switch macOS Spaces | |
,
,
,
| List/click app menus and extras | |
,
| Target status-bar items by name/index | |
,
,
,
,
| Interact with Dock items | |
,
,
,
,
| Drive system dialogs (open/save/etc.) | |
,
,
| Screenshot screen/window/menu bar (+analyze) | |
,
,
,
,
| Enumerate apps, windows, screens, permissions | |
,
| Inspect native + MCP tools | |
,
,
,
,
| Manage credentials/providers/settings | |
,
| Check/grant required macOS permissions | |
,
,
| Execute
automation scripts | |
(ms) | Millisecond delays between steps | |
,
,
| Prune sessions and caches | |
,
,
,
, audio | Natural-language multi-step automation | |
,
,
,
,
| Manage external MCP servers and serve Peekaboo |
Models and providers
OpenAI: GPT-5.1 (default) and GPT-4.1/4o vision
Anthropic: Claude 4.x
xAI: Grok 4-fast reasoning + vision
Google: Gemini 2.5 (pro/flash)
Local: Ollama (llama3.3, llava, etc.)
Set providers via PEEKABOO_AI_PROVIDERS or peekaboo config add.
Learn more
Command reference: docs/commands/
Architecture: docs/ARCHITECTURE.md
Building from source: docs/building.md
Testing guide: docs/testing/tools.md
MCP setup: docs/commands/mcp.md
Permissions: docs/permissions.md
Ollama/local models: docs/ollama.md
Agent chat loop: docs/agent-chat.md
Service API reference: docs/service-api-reference.md
Development basics
Requirements: macOS 15+, Xcode 16+/Swift 6.2. Node 22+ only if you run the pnpm docs/build helper scripts (core CLI/app/MCP are Swift-only).
Install deps:
pnpm installthenpnpm run build:cliorpnpm run test:safe.Lint/format:
pnpm run lint && pnpm run format.
License
MIT