Peekaboo MCP Server

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).

Install

• macOS app + CLI (Homebrew):

  brew install steipete/tap/peekaboo
  

• MCP 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"
#       }
#     }
#   }
# }

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 install then pnpm run build:cli or pnpm run test:safe.
• Lint/format: pnpm run lint && pnpm run format.

License

MIT