MCP Directory

How to add Peekaboo to Claude Desktop

macOS screen capture, AI visual analysis, and full GUI automation for AI agents. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 4.8k★ · stdio · apikey

Claude Desktop config for Peekaboo

npx -y @steipete/peekaboo
{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/peekaboo"
      ],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "openai/gpt-5.5,anthropic/claude-opus-4-8"
      }
    }
  }
}

Setup steps

  1. 1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
  2. 2Paste the Peekaboo config below under the top-level "mcpServers" key.
  3. 3Fill in any placeholder secrets (API keys, paths) in the snippet.
  4. 4Save the file, then fully quit and reopen Claude Desktop.
  5. 5Open a chat and confirm Peekaboo's tools appear under the 🔌 tools menu.

Before you start

  • macOS 15.0+ (Sequoia)
  • Node.js 22+ (for the npm MCP wrapper)
  • Screen Recording permission
  • Accessibility permission
  • Event Synthesizing permission (for keyboard/coordinate input)
  • AI provider API key for hosted visual analysis (optional)

What Peekaboo can do in Claude Desktop

see

Capture and annotate the current UI, returning a snapshot plus opaque element IDs.

click

Click an element by ID, label/query, or coordinates, with optional wait and foreground delivery.

type

Enter text with pacing/clear/profile options into the targeted app.

set-value

Directly set a settable accessibility value on an element.

perform-action

Invoke a named accessibility action (e.g. AXPress) on an element.

press

Send special keys and key sequences with count/delay/hold options.

hotkey

Send modifier combos such as cmd/ctrl/alt/shift chords.

paste

Paste text/file/image payloads with clipboard restore.

Security

Requires macOS Screen Recording and Accessibility permissions (and Event Synthesizing for keyboard/coordinate input). The server can capture the entire screen and fully control the GUI (clicks, typing, app/window/menu actions), so it has broad access to the user's desktop. AI provider API keys are supplied via PEEKABOO_AI_PROVIDERS / config; no key is needed for capture/automation alone but is required for AI analysis with hosted providers.

Peekaboo + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the Peekaboo config there under the "mcpServers" key and restart the client.

Is Peekaboo safe to use with Claude Desktop?

Requires macOS Screen Recording and Accessibility permissions (and Event Synthesizing for keyboard/coordinate input). The server can capture the entire screen and fully control the GUI (clicks, typing, app/window/menu actions), so it has broad access to the user's desktop. AI provider API keys are supplied via PEEKABOO_AI_PROVIDERS / config; no key is needed for capture/automation alone but is required for AI analysis with hosted providers.

Which platforms are supported?

Peekaboo targets macOS 15.0+ (Sequoia). Community rewrites exist for Windows (PeekabooWin) and Linux (PeekabooX), but the main project is macOS-only.

Do I need an AI API key to use it?

No. Screen capture and GUI automation work without any AI key. An AI provider key (set via PEEKABOO_AI_PROVIDERS or peekaboo config add) is only needed for AI visual analysis with hosted providers; local models via Ollama/LM Studio are also supported.

What permissions does it require?

macOS Screen Recording and Accessibility permissions are required, plus Event Synthesizing for keyboard and coordinate-based input. Run 'peekaboo permissions request-event-synthesizing' if it reports as missing.

View repo Full Peekaboo page