seeLABSCO SUMMARY
Public MCP servers here are background-only, and refusals happen before dispatch.
Foreground actions, shared desktop input and ambient browser auto-connect are rejected before anything runs, so an MCP client cannot quietly take over your screen — establishing a browser connection is a separate, explicit foreground step. verify_state is the other design decision worth copying: it polls real accessibility state and returns unknown rather than guessing when the evidence is ambiguous. The capture tool writes video and frames, so use tool filters before exposing this to a client you do not control.
What it is
A macOS CLI and menu-bar app for screen capture, accessibility inspection and native UI automation, with peekaboo mcp running the same toolset as an MCP server over stdio. The core loop is observe, pick an element from the result, act on it — the map comes back with opaque element ids rather than raw coordinates.
What you get
- A structured UI map of a running app or the whole screen, with element ids to act on —
see, backed byscreen listandwindow list - Native interaction: clicking that tries accessibility actions before synthetic input, plus typing, key presses, scrolling and dragging —
click, and the CLI'stype,press,scroll,drag - Action-first additions that skip synthetic input entirely: setting an accessibility value directly, and invoking a named accessibility action on an element —
set_value,action - Waiting that replaces fixed sleeps: 1 to 8 predicates about window existence, bounds, or element existence, value, enabled and selected state, polled every 100 ms for at most 10 seconds, reported as satisfied, unsatisfied or a conservative unknown —
verify_state - Bounded recording of a screen, window or region that writes retained frames,
contact.png,metadata.jsonand optional MP4 —capture - A natural-language agent run over the same tools —
agentfrom the CLI, and a nested background-only agent tool over MCP - Window-pinned automation: list Safari's windows, take the
window_id, and keep every subsequent call bound to that exact window
Requirements
macOS 15 or later. The CLI installs with brew install steipete/tap/peekaboo; the npm package @steipete/peekaboo 4.2.3 needs Node.js 22 or later and includes the CLI plus the MCP launcher. Screen Recording permission is required for capture and Accessibility permission for inspection and control — check both with peekaboo permissions status. The MCP server runs over stdio; HTTP and SSE transports are reserved and currently fail with an explicit error. Agent runs need a model provider configured under ~/.peekaboo. MIT licensed.
Setup effort
One command — brew install steipete/tap/peekaboo
USE CASES
01
Automating a Mac app reliably
Take the structured UI map, act on the element ids it returns, and pin every call to one window_id so a second window cannot steal the action.
02
Waiting for the app to settle without guessing a sleep
State the conditions — this window exists, this field reads Ready — and poll them for a bounded time instead of hard-coding a delay that is either too short or too slow.
03
Changing a field without simulating typing
Set the accessibility value directly, or invoke the element's named accessibility action — fewer moving parts than synthetic keystrokes.
04
Recording evidence of what happened
Capture the screen, window or region to frames and video with metadata written alongside, for a bug report or a review.
8 tools
Listed in project docs. Your client may show a different list.
clickcaptureset_valueactionverify_statepasteagentBEFORE YOU INSTALL
What to know first
Tools you get
8 tools named in the project's documentation. These are only the tools the documentation explicitly calls MCP tools, such as capture, see, click and paste; the server may expose more, and it does not say which CLI commands, such as scroll or drag, are also MCP tools.
Where it runs
Both documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
brew install steipete/tap/peekabooGrant permissions: run peekaboo permissions grant, which opens System Settings to the right pane — you need Screen Recording and Accessibility. Re-run peekaboo permissions status until both are green.
Add the configuration under MCP Clients to your MCP client config
MCP Clients
npm Package
NPM PACKAGE · JSON
{
"mcpServers": {
"peekaboo": {
"command": "npx",
"args": [
"-y",
"@steipete/peekaboo",
"mcp"
]
}
}
}Local Binary
LOCAL BINARY · JSON
{
"mcpServers": {
"peekaboo": {
"command": "<YOUR_PATH_TO_PEEKABOO>",
"args": [
"mcp"
]
}
}
}
