Peekaboo

Peekaboo MCP: Lightning-fast macOS Screenshots 🚀

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

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

🔧 Configuration

Configuration Precedence

Settings follow this precedence (highest to lowest):

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

Available Options

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

1. Screen Recording (Required):

   • System Settings → Privacy & Security → Screen & System Audio Recording
   • Enable for Terminal, Claude Desktop, or your IDE

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

• Blog Post

🐛 Troubleshooting

Enable debug logging for more details:

export PEEKABOO_LOG_LEVEL=debug
peekaboo list server_status

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

📝 License

MIT License - see 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 for migration details.