Peekaboo MCP Server: Setup for Claude, Cursor and Other Apps on Mac

• Take a screenshot

  Takes a screenshot of a display, the front window, one app's window or the menu bar. It saves a file or returns the picture to the assistant. It does not map the screen's buttons.

  Try: “Take a screenshot of my Safari window.”

  Files · image

• Record frames from screen or video

  Captures live frames from a screen, window or region, or reads a video file, and returns the kept PNG frames, a contact sheet and a metadata file.

  Try: “Capture 10 seconds of the Xcode window and show me what changed.”

  Files · capture

• Ask an AI model about an image file

  Sends an image file from your disk (up to 10 MiB) to the AI provider you configured and returns its answer to your question about it.

  Try: “What text is visible in /tmp/chart.png?”

  Files · analyze

• Control an existing Chrome page

  Controls and reads Chrome pages over its debugging connection. In the default background-only mode most page actions are refused, and they need the server started with --allow-foreground.

  Try: “Connect to my Chrome and list the open tabs.”

  Write · browser

• Check macOS permissions

  Reports whether Screen Recording and Accessibility permissions are granted, and whether synthetic input is limited.

  Try: “Do I have the permissions Peekaboo needs?”

  Read · permissions

• Wait for a set time

  Pauses for a number of milliseconds, for example to let an animation finish.

  Try: “Wait 2 seconds, then look at the screen again.”

  Read · sleep

• Screenshot plus a map of the controls

  Captures a window or screen and builds a list of its buttons, fields and text with IDs that the click and type tools can use. It can add OCR text found by Apple Vision on your Mac.

  Try: “Look at the Finder window and list its buttons.”

  Files · see

• Read the UI text without a screenshot

  Reads the visible text, labels, buttons and field states of an app from its accessibility tree. No screenshot is taken.

  Try: “Read the text fields in the Settings window.”

  Read · inspect_ui

• Wait until a window shows what you expect

  Polls an app window every 100 ms, up to 10 seconds, until conditions you set are met, such as a field holding a given value. It never clicks or types.

  Try: “Wait until the Name field in TextEdit says Ready.”

  Read · verify_state

• Click a button, link or point

  Clicks an element from a recent see result, a text query, or coordinates. By default it clicks in the background without moving your mouse.

  Try: “Click the Save button in TextEdit.”

  Write · click

• Type text into an app

  Types text into a field of a window you observed first. It can clear the field before typing. By default it sends the keystrokes in the background.

  Try: “Type 'hello' into the Name field.”

  Write · type

• Set a field's value directly

  Sets the value of a form field through accessibility, without sending keystrokes. The field must allow it.

  Try: “Set the Volume slider to 50.”

  Write · set_value

• Select text or place the cursor

  Selects a piece of literal text, or puts the cursor before or after it, in a field. It does not type or use the clipboard.

  Try: “Select the word 'draft' in the note body.”

  Write · select_text

• Run a named accessibility action

  Runs an accessibility action such as AXPress or AXIncrement on an element. In background-only mode actions that would bring windows forward are refused.

  Try: “Press the Increment control on the stepper.”

  Write · action

• Scroll a window or element

  Scrolls an element or an exact window point in the background, without taking your pointer.

  Try: “Scroll the page down in the Safari window.”

  Write · scroll

• Press keys or shortcuts

  Presses a key or a chord such as Cmd+C, to a window you observed first.

  Try: “Press Return in the Safari address bar.”

  Write · press

• Drag one thing onto another

  Drags between two elements or points inside one window, along a straight path of limited length.

  Try: “Drag the file icon into the Trash folder in the sidebar.”

  Write · drag

• Move the mouse pointer

  Moves your real mouse cursor to a spot or element. It always uses your shared cursor, so it needs foreground mode.

  Try: “Move the pointer to the Dock.”

  Write · move

• List, launch or quit apps

  Lists running apps and can quit or hide them. In the default background-only mode, launching only checks that an app is already running.

  Try: “Quit Slack.”

  Write · app

• List and move windows

  Lists windows and can close, minimize, restore, maximize, move or resize them. Bringing a window to the front needs foreground mode.

  Try: “Close the second Safari window.”

  Write · window

• List or click menu items

  Lists an app's menu items and clicks one by path, such as File > Save.

  Try: “Click File > Save in TextEdit.”

  Write · menu

• Read the clipboard

  Reads the macOS clipboard or saves it to a named slot. In the default mode it cannot change the clipboard. Setting, clearing and restoring it need foreground mode.

  Try: “What is on my clipboard right now?”

  Files · clipboard

• Paste text into an app

  Pastes text into one exact window you observed first. With a separate --allow-temporary-clipboard flag it can briefly use the clipboard and restore it.

  Try: “Paste this paragraph into the Notes window.”

  Write · paste

• Let Peekaboo plan a multi-step task

  Runs a natural-language task using the AI provider you configured. It plans and performs steps with Peekaboo's own tools. When started through MCP it stays background-only.

  Try: “Open Safari, go to github.com and search for Peekaboo.”

  Write · agent

• Look at the Dock

  Lists the items in the Dock. Launching, menus, hiding and showing the Dock need foreground mode.

  Try: “What apps are in my Dock?”

  Read · dock

• Read and answer system dialogs

  Lists dialogs and clicks buttons, types into fields or dismisses them, for an app you name.

  Try: “Click OK on the TextEdit dialog.”

  Write · dialog

• List Spaces or move a window

  Lists your macOS Spaces and can move a window to another Space. Switching Spaces needs foreground mode.

  Try: “Move the Safari window to Space 3.”

  Write · space

Watch out for

• It can see and act in any app on your Mac

  With Screen Recording and Accessibility permission it can read any window and click or type into it. Close windows with private data, and limit tools with PEEKABOO_ALLOW_TOOLS if you only need screenshots. github.com

• It can close windows and quit apps

  The window and app tools can close windows and quit apps, which can lose unsaved work. Save your work before you hand over control. github.com

• Screenshots may go to an AI provider

  The analyze tool sends an image file to the provider you configured. The agent tool works with that provider too. Leave the provider unset if you do not want that. github.com

• The clipboard can be read

  The clipboard tool reads what you last copied, which may include passwords. Remove it with PEEKABOO_DISABLE_TOOLS if you do not need it. github.com

• Foreground mode lifts the safety limits

  Starting the server with --allow-foreground lets it take your mouse, change the clipboard and switch Spaces. Leave it off unless you are watching. github.com

Security advisories