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

• API Documentation
• Architecture Overview
• Contributing Guide
• 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 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.

Changelog

All notable changes to Peekaboo will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[2.0.2] - 2025-07-03

Fixed

• Actually fixed compatibility with macOS Sequoia 26 by ensuring LC_UUID load command is generated during linking
• The v2.0.1 fix was incomplete - the binary was still missing LC_UUID
• Verified both x86_64 and arm64 architectures now contain proper LC_UUID load commands

[2.0.1] - 2025-07-03

Fixed

• Fixed compatibility with macOS Sequoia 26 (pre-release) by preserving LC_UUID load command during binary stripping

[2.0.0] - 2025-07-03

🎉 Major Features

Standalone AI Analysis in CLI

• Added native AI analysis capability directly to Swift CLI - analyze images without the MCP server
• Support for multiple AI providers: OpenAI GPT-4 Vision and local Ollama models
• Automatic provider selection and fallback mechanisms
• Perfect for automation, scripts, and CI/CD pipelines
• Example: peekaboo analyze screenshot.png "What error is shown?"

Configuration File System

• Added comprehensive JSONC (JSON with Comments) configuration file support
• Location: ~/.config/peekaboo/config.json
• Features:
  • Persistent settings across terminal sessions
  • Environment variable expansion using ${VAR_NAME} syntax
  • Comments support for better documentation
  • Tilde expansion for home directory paths
• New config subcommand with init, show, edit, and validate operations
• Configuration precedence: CLI args > env vars > config file > defaults

🚀 Improvements

Enhanced CLI Experience

• Completely redesigned help system following Unix conventions
  • Examples shown first for better discoverability
  • Clear SYNOPSIS sections
  • Common workflows documented
  • Exit status codes for scripting
• Added standalone CLI build script (scripts/build-cli-standalone.sh)
  • Build without npm/Node.js dependencies
  • System-wide installation support with --install flag

Code Quality

• Added comprehensive test coverage for AI analysis functionality
• Fixed all SwiftLint violations
• Improved error handling and user feedback
• Better code organization and maintainability

📝 Documentation

• Added configuration file documentation to README
• Expanded CLI usage examples
• Documented AI analysis capabilities
• Added example scripts and automation workflows
• Removed outdated tool-description.md

🔧 Technical Changes

• Migrated from direct environment variable usage to ConfigurationManager
• Implemented proper JSONC parser with comment stripping
• Added thread-safe configuration loading
• Improved Swift-TypeScript interoperability

💥 Breaking Changes

• Version bump to 2.0 reflects the significant expansion from MCP-only to dual CLI/MCP tool
• Configuration file takes precedence over some environment variables (but maintains backward compatibility)

🐛 Bug Fixes

• Fixed ArgumentParser command structure for proper subcommand execution
• Resolved configuration loading race conditions
• Fixed help text display issues

⬆️ Dependencies

• Swift ArgumentParser 1.5.1
• Maintained all existing npm dependencies

[1.1.0] - Previous Release

• Initial MCP server implementation
• Basic screenshot capture functionality
• Window and application listing
• Integration with Claude Desktop and Cursor IDE