Peekaboo MCP
Peekaboo is a macOS CLI & optional MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.
What is Peekaboo MCP?
Peekaboo MCP is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to peekaboo is a macos cli & optional mcp server that enables ai agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote ai mo...
Peekaboo is a macOS CLI & optional MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.
This server falls under the Browser Automation category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Peekaboo is a macOS CLI & optional MCP server that enables A
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx peekaboo-mcpConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Peekaboo MCP
Peekaboo is a macOS screen capture and GUI automation tool that exposes both a CLI and an MCP server, enabling AI agents to take pixel-accurate screenshots, annotate UI elements with accessible IDs, and then click, type, scroll, drag, and otherwise drive any macOS application programmatically. It connects to multiple AI providers (OpenAI, Anthropic, xAI/Grok, Google Gemini, Ollama, and OpenAI-compatible endpoints) via the PEEKABOO_AI_PROVIDERS environment variable, allowing visual question answering and natural-language agent flows. Developers use it to automate repetitive GUI workflows, test macOS apps, or give AI assistants the ability to see and interact with the desktop.
Prerequisites
- macOS 15.0 (Sequoia) or later
- Node.js 22 or later (for the MCP server via npx)
- Screen Recording permission granted to the terminal / MCP host application
- Accessibility permission granted for click/type/hotkey automation
- At least one AI provider API key (e.g., OPENAI_API_KEY) for visual analysis features
Install the Peekaboo CLI (optional but recommended)
Install the full macOS app and CLI via Homebrew. This provides the peekaboo binary and the Peekaboo.app Bridge host that handles permission-bound automation.
brew install steipete/tap/peekabooGrant required macOS permissions
Peekaboo requires Screen Recording and Accessibility permissions. Use the built-in permissions command to check current status and request missing ones.
peekaboo permissions status
peekaboo permissions request-screen-recording
peekaboo permissions request-event-synthesizingConfigure AI providers
Set the PEEKABOO_AI_PROVIDERS environment variable to specify which AI models Peekaboo uses for image analysis and agent flows. Multiple providers are listed comma-separated.
export PEEKABOO_AI_PROVIDERS="openai/gpt-4o,anthropic/claude-opus-4-5"
# Or save permanently via the config command:
peekaboo config addTest screen capture
Verify everything works by capturing the full screen. The --retina flag enables 2x Retina resolution output.
peekaboo image --mode screen --retina --path ~/Desktop/test.pngAdd Peekaboo as an MCP server
Configure your MCP client to run Peekaboo as an MCP server using npx. No global install is needed — npx downloads and caches the package automatically.
{
"mcpServers": {
"peekaboo": {
"command": "npx",
"args": ["-y", "@steipete/peekaboo"],
"env": {
"PEEKABOO_AI_PROVIDERS": "openai/gpt-4o,anthropic/claude-opus-4-5"
}
}
}
}Peekaboo MCP Examples
Client configuration
MCP configuration for Claude Desktop or Claude Code to run Peekaboo as an MCP server with OpenAI for visual analysis.
{
"mcpServers": {
"peekaboo": {
"command": "npx",
"args": ["-y", "@steipete/peekaboo"],
"env": {
"PEEKABOO_AI_PROVIDERS": "openai/gpt-4o,anthropic/claude-opus-4-5"
}
}
}
}Prompts to try
Example prompts to use with Peekaboo through an MCP client once the server is running.
- "Take a screenshot of my screen and describe what you see"
- "Open Safari and navigate to github.com without bringing it to the foreground"
- "Click the Submit button in the active form on screen"
- "Run the agent: open Notes, create a new note titled 'MCP Test', and type three bullet points"
- "What error message is showing in the terminal window?"Troubleshooting Peekaboo MCP
peekaboo image fails with permission denied or returns a black screenshot
Run 'peekaboo permissions status' to check which permissions are missing. Grant Screen Recording to the terminal app (or to Peekaboo.app if using the Bridge host) in System Settings > Privacy & Security > Screen Recording, then relaunch the terminal.
click and type commands have no effect on the target application
Accessibility permission must be granted to the process sending events. Run 'peekaboo permissions request-event-synthesizing' and approve in System Preferences. If the app only accepts foreground input, add the --foreground flag to your click/type command.
npx -y @steipete/peekaboo fails with 'unsupported platform' or Node version error
Peekaboo requires Node.js 22 or later and macOS 15 (Sequoia). Run 'node --version' to check your version and update via 'brew upgrade node' or the Node.js installer at nodejs.org.
Frequently Asked Questions about Peekaboo MCP
What is Peekaboo MCP?
Peekaboo MCP is a Model Context Protocol (MCP) server that peekaboo is a macos cli & optional mcp server that enables ai agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote ai models. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Peekaboo MCP?
Follow the installation instructions on the Peekaboo MCP GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Peekaboo MCP?
Peekaboo MCP works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Peekaboo MCP free to use?
Yes, Peekaboo MCP is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
Peekaboo MCP Alternatives — Similar Browser Automation Servers
Looking for alternatives to Peekaboo MCP? Here are other popular browser automation servers you can use with Claude, Cursor, and VS Code.
Chrome DevTools MCP
★ 40.6kAI-powered Chrome automation server with natural language element detection. Control Chrome browser through MCP protocol for testing, debugging, and performance analysis. Features 91% accuracy in element location, works with free AI models, and suppo
UI TARS Desktop
★ 34.9k📇 🏠 - Browser automation capabilities using Puppeteer, both support local and remote browser connection.
Playwright
★ 32.8kA production-ready browser automation server that enables AI assistants to interact with web pages using tools for navigation, element interaction, and data extraction. It features a built-in Inspector UI and robust crash recovery for reliable automa
Page Agent
★ 18.0kJavaScript in-page GUI agent. Control web interfaces with natural language.
Chrome
★ 11.7kAn extension-based MCP server that enables AI assistants to control your browser, leveraging existing sessions and login states for automation and content analysis. It provides over 20 tools for semantic tab search, interactive element manipulation,
LAMDA
★ 7.8kThe most powerful Android RPA agent framework, next generation mobile automation.
Browse More Browser Automation MCP Servers
Explore all browser automation servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Peekaboo MCP in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Peekaboo MCP?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.