Skip to content

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.

License

Notifications You must be signed in to change notification settings

steipete/Peekaboo

Repository files navigation

Peekaboo MCP: Lightning-fast macOS Screenshots πŸš€

Peekaboo Banner

npm version License: MIT macOS Swift Node.js

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 Claude Code

Run the following command:

claude mcp add-json 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"
    }
}'

Alternatively, if you've already installed the server via Claude desktop, you can run:

claude mcp add-from-claude-desktop

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

Setting Config File Environment Variable Description
AI Providers aiProviders.providers PEEKABOO_AI_PROVIDERS Comma-separated list (e.g., "openai/gpt-4o,ollama/llava:latest")
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

  • 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

πŸ› 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:

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

About

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.

Topics

Resources

License

Stars

Watchers

Forks