Give Your AI Agents Supernatural Vision on macOS.
Peekaboo is a macOS-only MCP server for lightning-fast, non-intrusive screen capture and Visual Question Answering (VQA)."Without screenshots, agents debug blind—Peekaboo gives them eyes."
What is Peekaboo?
Peekaboo bridges the gap between AI assistants and the visual content on your Mac's screen. It empowers AI agents to see, understand, and interact with your macOS environment non-intrusively, unlocking new levels of automation and intelligent debugging.
Capture Screenshots
Entire screen, specific apps, or individual windows.
Analyze Visuals
AI vision models (local/cloud) answer questions about images.
List System Info
Running apps and their windows for targeted actions.
Non-Intrusive
No focus changes or workflow interruptions during capture.
Key Capabilities
Uses Apple's ScreenCaptureKit for instant captures without focus changes.
Fuzzy matching finds the right window even with partial names or variations.
Ask questions about screenshots using GPT-4o, Claude, LLaVA, or Qwen2-VL.
Run entirely locally with Ollama for full data control, or use cloud providers.
One-click install via Cursor, or simple npm/npx commands. Configurable via ENV.
Clean JSON API, TypeScript support, comprehensive logging, and robust error handling.
Core Tools for Agents
The primary tool for capturing macOS screen content. Automatically removes window shadows/frames. Can optionally analyze the image with a question.
Targets: entire screen, specific apps (fuzzy match), individual windows by title/index, or frontmost. Formats: PNG, JPG, or Base64 data (for app windows). Special handling for screen captures (file-only) and browser helper filtering.
Tech & Architecture
TypeScript & Swift: The Best of Both Worlds
Peekaboo leverages TypeScript for its robust MCP SDK support and easy npm distribution, while a native Swift CLI provides direct, high-performance access to macOS's ScreenCaptureKit.
- ScreenCaptureKit: Ensures non-intrusive, lightning-fast captures without focus changes.
- Node.js MCP Server: Handles agent communication, schema validation, and AI provider orchestration.
- Swift CLI: Performs the actual screen capture and system interaction, outputting structured JSON.
- Configurable: Extensive environment variables for tailoring AI providers, logging, and paths.
Get Peekaboo
Ready to give your AI agents eyes? Peekaboo is easy to install and configure. Requires macOS 14.0+ and Node.js 20.0+.
For Cursor IDE Users:
One-click install!
Via NPM/NPX:
npx -y @steipete/peekaboo-mcp(Includes details on environment variables, AI provider setup, Ollama, and macOS permissions)