MCP Directory

How to add Peekaboo to Cursor

macOS screen capture, AI visual analysis, and full GUI automation for AI agents. Paste the config into ~/.cursor/mcp.json and restart Cursor.

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

Cursor 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 Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
  2. 2Paste the Peekaboo config below into the "mcpServers" object.
  3. 3Fill in placeholder secrets, then save.
  4. 4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
  5. 5Ask Cursor to use one of Peekaboo's tools to confirm it's connected.

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 Cursor

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

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the Peekaboo config there under the "mcpServers" key and restart the client.

Is Peekaboo safe to use with Cursor?

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