MCP Directory

How to add Peekaboo to Windsurf

macOS screen capture, AI visual analysis, and full GUI automation for AI agents. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf 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 Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Peekaboo config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Peekaboo's tools become available to Cascade.

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 Windsurf

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 + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Peekaboo config there under the "mcpServers" key and restart the client.

Is Peekaboo safe to use with Windsurf?

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