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.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Peekaboo MCPtake a screenshot of my current screen and describe what you see"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-beta4) 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
# Capture full screen at Retina scale and save to Desktop
peekaboo image --mode screen --retina --path ~/Desktop/screen.png
# Click a button by label (captures, resolves, and clicks in one go)
peekaboo see --app Safari --json | jq -r '.data.snapshot_id' | read SNAPSHOT
peekaboo click --on "Reload this page" --snapshot "$SNAPSHOT"
# Run a natural-language automation
peekaboo "Open Notes and create a TODO list with three items"
# Run as an MCP server (Claude/Cursor)
npx -y @steipete/peekaboo
# Minimal Claude Desktop config snippet (Developer → Edit Config):
# {
# "mcpServers": {
# "peekaboo": {
# "command": "npx",
# "args": ["-y", "@steipete/peekaboo"],
# "env": {
# "PEEKABOO_AI_PROVIDERS": "openai/gpt-5.1,anthropic/claude-opus-4"
# }
# }
# }
# }Command | Key flags / subcommands | What it does |
| Capture and annotate UI, return snapshot + element IDs | |
| 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 | |
| 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 Peekaboo tools | |
| Manage credentials/providers/settings | |
| Check/grant required macOS permissions | |
| Execute | |
| Millisecond delays between steps | |
| Prune snapshots and caches | |
| Natural-language multi-step automation | |
| Run Peekaboo as an MCP server |
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
Resources
Looking for Admin?
Admins can modify the Dockerfile, update the server description, and track usage metrics. If you are the server author, to authenticate as an admin.