Peekaboo MCP

Peekaboo MCP: Lightning-fast macOS Screenshots 🚀

Peekaboo Banner

Peekaboo is a powerful macOS utility for capturing screenshots and analyzing them with AI vision models. It works both as a standalone CLI tool (recommended) and as an MCP server for AI assistants like Claude Desktop and Cursor.

🎯 Choose Your Path

🖥️ CLI Tool (Recommended for Most Users)

Perfect for:

Command-line workflows and automation
Shell scripts and CI/CD pipelines
Quick screenshots and AI analysis
System administration tasks

🤖 MCP Server (For AI Assistants)

Perfect for:

Claude Desktop integration
Cursor IDE workflows
AI agents that need visual context
Interactive AI debugging sessions

What is Peekaboo?

Peekaboo bridges the gap between visual content on your screen and AI understanding. It provides:

Lightning-fast screenshots of screens, applications, or specific windows
AI-powered image analysis using GPT-4 Vision, Claude, or local models
Window and application management with smart fuzzy matching
Privacy-first operation with local AI options via Ollama
Non-intrusive capture without changing window focus

🚀 Quick Start: CLI Tool

Installation

# Option 1: Homebrew (Recommended)
brew tap steipete/tap
brew install peekaboo

# Option 2: Direct Download
curl -L https://github.com/steipete/peekaboo/releases/latest/download/peekaboo-macos-universal.tar.gz | tar xz
sudo mv peekaboo-macos-universal/peekaboo /usr/local/bin/

# Option 3: npm (includes MCP server)
npm install -g @steipete/peekaboo-mcp

# Option 4: Build from source
git clone https://github.com/steipete/peekaboo.git
cd peekaboo
./scripts/build-cli-standalone.sh --install

Basic Usage

# Capture screenshots
peekaboo image --app Safari --path screenshot.png
peekaboo image --mode frontmost
peekaboo image --mode screen --screen-index 0

# List applications and windows
peekaboo list apps
peekaboo list windows --app "Visual Studio Code"

# Analyze images with AI
peekaboo analyze screenshot.png "What error is shown?"
peekaboo analyze ui.png "Find all buttons" --provider ollama

# Configure settings
peekaboo config init                    # Create config file
peekaboo config edit                    # Edit in your editor
peekaboo config show --effective        # Show current settings

Configuration

Create a persistent configuration file at ~/.config/peekaboo/config.json:

peekaboo config init

Example configuration:

{
  // AI Provider Settings
  "aiProviders": {
    "providers": "openai/gpt-4o,ollama/llava:latest",
    "openaiApiKey": "${OPENAI_API_KEY}",  // Supports env var expansion
    "ollamaBaseUrl": "http://localhost:11434"
  },
  
  // Default Settings
  "defaults": {
    "savePath": "~/Desktop/Screenshots",
    "imageFormat": "png",
    "captureMode": "window",
    "captureFocus": "auto"
  }
}

Common Workflows

# Capture and analyze in one command
peekaboo image --app Safari --path /tmp/page.png && \
  peekaboo analyze /tmp/page.png "What's on this page?"

# Monitor active window changes
while true; do
  peekaboo image --mode frontmost --json-output | jq -r '.data.saved_files[0].window_title'
  sleep 5
done

# Batch analyze screenshots
for img in ~/Screenshots/*.png; do
  peekaboo analyze "$img" "Summarize this screenshot"
done

🤖 MCP Server Setup

For AI assistants like Claude Desktop and Cursor, Peekaboo provides a Model Context Protocol (MCP) server.

For Claude Desktop

Edit your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": ["-y", "@steipete/peekaboo-mcp"],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "openai/gpt-4o,ollama/llava:latest",
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

For Cursor IDE

Add to your Cursor settings:

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": ["-y", "@steipete/peekaboo-mcp"],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "openai/gpt-4o,ollama/llava:latest",
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

MCP Tools Available

image - Capture screenshots
list - List applications, windows, or check status
analyze - Analyze images with AI vision models

🔧 Configuration

Configuration Precedence

Settings follow this precedence (highest to lowest):

Command-line arguments
Environment variables
Configuration file (~/.config/peekaboo/config.json)
Built-in defaults

Available Options

Setting	Config File	Environment Variable	Description
AI Providers	`aiProviders.providers`	`PEEKABOO_AI_PROVIDERS`	Comma-separated list (e.g., "openai/gpt-4o,ollama/llava")
OpenAI API Key	`aiProviders.openaiApiKey`	`OPENAI_API_KEY`	Required for OpenAI provider
Anthropic API Key	`aiProviders.anthropicApiKey`	`ANTHROPIC_API_KEY`	For Claude Vision (coming soon)
Ollama URL	`aiProviders.ollamaBaseUrl`	`PEEKABOO_OLLAMA_BASE_URL`	Default: http://localhost:11434
Default Save Path	`defaults.savePath`	`PEEKABOO_DEFAULT_SAVE_PATH`	Where screenshots are saved (default: current directory)
Log Level	`logging.level`	`PEEKABOO_LOG_LEVEL`	trace, debug, info, warn, error, fatal
Log Path	`logging.path`	`PEEKABOO_LOG_FILE`	Log file location
CLI Binary Path	-	`PEEKABOO_CLI_PATH`	Override bundled Swift CLI path (advanced usage)

Environment Variable Details

AI Provider Configuration

PEEKABOO_AI_PROVIDERS: Comma-separated list of AI providers to use for image analysis
- Format: provider/model,provider/model
- Example: "openai/gpt-4o,ollama/llava:latest"
- The first available provider will be used
- Default: "openai/gpt-4o,ollama/llava:latest"
OPENAI_API_KEY: Your OpenAI API key for GPT-4 Vision
- Required when using the openai provider
- Get your key at: https://platform.openai.com/api-keys
ANTHROPIC_API_KEY: Your Anthropic API key for Claude Vision
- Will be required when Claude Vision support is added
- Currently not implemented
PEEKABOO_OLLAMA_BASE_URL: Base URL for your Ollama server
- Default: http://localhost:11434
- Use for custom Ollama installations or remote servers

Default Behavior

PEEKABOO_DEFAULT_SAVE_PATH: Default directory for saving screenshots
- Default: Current working directory
- Supports tilde expansion (e.g., ~/Desktop/Screenshots)
- Created automatically if it doesn't exist

Logging and Debugging

PEEKABOO_LOG_LEVEL: Control logging verbosity
- Options: trace, debug, info, warn, error, fatal
- Default: info
- Use debug or trace for troubleshooting
PEEKABOO_LOG_FILE: Custom log file location
- Default: /tmp/peekaboo-mcp.log (MCP server)
- For CLI, logs are written to stderr by default

Advanced Options

PEEKABOO_CLI_PATH: Override the bundled Swift CLI binary path
- Only needed if using a custom-built CLI binary
- Default: Uses the bundled binary

Using Environment Variables

Environment variables can be set in multiple ways:

# For a single command
PEEKABOO_AI_PROVIDERS="ollama/llava:latest" peekaboo analyze image.png "What is this?"

# Export for the current session
export OPENAI_API_KEY="sk-..."
export PEEKABOO_DEFAULT_SAVE_PATH="~/Desktop/Screenshots"

# Add to your shell profile (~/.zshrc or ~/.bash_profile)
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc

🎨 Setting Up Local AI with Ollama

For privacy-focused local AI analysis:

# Install Ollama
brew install ollama
ollama serve

# Download vision models
ollama pull llava:latest       # Recommended
ollama pull qwen2-vl:7b        # Lighter alternative

# Configure Peekaboo
peekaboo config edit
# Set providers to: "ollama/llava:latest"

📋 Requirements

macOS 14.0+ (Sonoma or later)
Screen Recording Permission (required)
Accessibility Permission (optional, for window focus control)

Granting Permissions

Screen Recording (Required):
- System Settings → Privacy & Security → Screen & System Audio Recording
- Enable for Terminal, Claude Desktop, or your IDE
Accessibility (Optional):
- System Settings → Privacy & Security → Accessibility
- Enable for better window focus control

🏗️ Building from Source

Prerequisites

macOS 14.0+ (Sonoma or later)
Node.js 20.0+ and npm
Xcode Command Line Tools (xcode-select --install)
Swift 5.9+ (included with Xcode)

Build Commands

# Clone the repository
git clone https://github.com/steipete/peekaboo.git
cd peekaboo

# Install dependencies
npm install

# Build everything (CLI + MCP server)
npm run build:all

# Build options:
npm run build         # TypeScript only
npm run build:swift   # Swift CLI only (universal binary)
./scripts/build-cli-standalone.sh         # Quick CLI build
./scripts/build-cli-standalone.sh --install # Build and install to /usr/local/bin

Creating Release Binaries

# Run all pre-release checks and create release artifacts
./scripts/release-binaries.sh

# Skip checks (if you've already run them)
./scripts/release-binaries.sh --skip-checks

# Create GitHub release draft
./scripts/release-binaries.sh --create-github-release

# Full release with npm publish
./scripts/release-binaries.sh --create-github-release --publish-npm

The release script creates:

peekaboo-macos-universal.tar.gz - Standalone CLI binary (universal)
@steipete-peekaboo-mcp-{version}.tgz - npm package
checksums.txt - SHA256 checksums for verification

🧪 Testing

# Test CLI directly
peekaboo list server_status
peekaboo image --mode screen --path test.png
peekaboo analyze test.png "What is shown?"

# Test MCP server
npx @modelcontextprotocol/inspector npx -y @steipete/peekaboo-mcp

📚 Documentation

🐛 Troubleshooting

Issue	Solution
`Permission denied`	Grant Screen Recording permission in System Settings
`Window not found`	Try using fuzzy matching or list windows first
`AI analysis failed`	Check API keys and provider configuration
`Command not found`	Ensure Peekaboo is in your PATH or use full path

Enable debug logging for more details:

export PEEKABOO_LOG_LEVEL=debug
peekaboo list server_status

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Open a Pull Request

📝 License

MIT License - see LICENSE file for details.

👤 Author

Created by Peter Steinberger - @steipete

🙏 Acknowledgments

Apple's ScreenCaptureKit for blazing-fast captures
The MCP team for the Model Context Protocol
The Swift and TypeScript communities

Note: This is Peekaboo v2.0, which introduces standalone CLI functionality alongside the original MCP server. For users upgrading from v1.x, see the CHANGELOG for migration details.

Install Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

A macOS utility that captures screenshots and analyzes them with AI vision, enabling AI assistants to see and interpret what's on your screen.

Related MCP Servers

mcp-screenshot
kazuph
A
security
A
license
A
quality
Provides screenshot and OCR capabilities for macOS.
Last updated -
1
35
10
JavaScript
MIT License
Safari Screenshot MCP Server
rogerheykoop
A
security
A
license
A
quality
Enables capturing high-quality native macOS screenshots using Safari through a Node.js server, supporting various sizes, zoom levels, and load wait times.
Last updated -
1
7
TypeScript
MIT License
AI Vision Debug MCP Server
samihalawa
A
security
A
license
A
quality
A Model Context Protocol server that provides AI vision capabilities for analyzing UI screenshots, offering tools for screen analysis, file operations, and UI/UX report generation.
Last updated -
26
1
JavaScript
ISC License
Screenshot MCP Server
codingthefuturewithai
-
security
F
license
-
quality
Enables AI tools to capture and process screenshots of a user's screen, allowing AI assistants to see and analyze what the user is looking at through a simple MCP interface.
Last updated -
1
Python

View all related MCP servers

Appeared in Searches

Desktop tools for showing pop-up windows during debugging