Add Screen Recording To Control Center, And The Second Process That Proves It Worked

Open System Settings, click Control Center in the sidebar, scroll the right pane to the Screen Recording module, and switch Show in Menu Bar to Always. On macOS 15 you can also open Control Center from the menu bar, click the small edit affordance at the bottom, and drag the Screen Recording control into a new slot. That is the path Apple Support, AppleVis, TechSmith, TheSweetBits, and the Apple Discussions thread at discussions.apple.com/thread/255457988 all describe. This page is about what happens when you ask an MCP client to do that path for you, and specifically about how the server proves to the client that the flip actually landed.

It cannot, and the Screen Recording toggle is a perfect example of why. The AXValue of the Show in Menu Bar popup updates the moment the click event posts, but the actual visual change in the menu bar can lag by a few hundred milliseconds. Worse, in macOS 15 the Control Center module sometimes briefly shows the new value while a background sync to the menu bar fails silently. The screenshot is the only ground truth. macos-use captures the System Settings window after every click, draws a red crosshair at the click coordinate, and writes it to /tmp/macos-use/<timestamp>_click_and_traverse.png so the client model can read it back and verify the row visually.

Because CGWindowListCreateImage, the API that produces the PNG, links ReplayKit on first call. Once ReplayKit is loaded into the address space of a long-lived process, it spins a background thread at roughly 19 percent CPU forever, and there is no public API to unload it. The doc comment at Sources/MCPServer/main.swift:382-385 spells this out: 'The actual CGWindowListCreateImage call runs in a subprocess (screenshot-helper) so that the ReplayKit framework, loaded as a side-effect by macOS, dies with the subprocess instead of spinning at ~19% CPU forever in the parent MCP server process.' Forking a child that exits after a few hundred milliseconds is the only way to keep the parent's CPU profile flat.

112 lines, including blanks and the shebang-style comment block at the top. The full source is at Sources/ScreenshotHelper/main.swift. It accepts three to seven arguments: a CGWindowID, an output PNG path, and an optional --click x,y plus --bounds x,y,w,h. It calls CGWindowListCreateImage with .optionIncludingWindow and the .boundsIgnoreFraming and .bestResolution flags, draws an annotated red crosshair (15-point arms, 10-point ring, 2-point line width, all scaled by the image-to-window ratio) when --click is provided, encodes the result as PNG via NSBitmapImageRep, writes it to disk, prints the path to stdout, and exits. The whole flow runs in well under a second on a 2024 MacBook Pro.

captureWindowScreenshot at Sources/MCPServer/main.swift:386-510. The fork itself is at main.swift:459-473: it constructs a Process(), points executableURL at './screenshot-helper' (resolved relative to CommandLine.arguments[0] at main.swift:436-438), and pipes both stdout and stderr. The wait is at main.swift:476-489: a 5.0-second deadline on a DispatchGroup, with process.terminate() on timeout. The whole call is invoked once per MCP tool response, at main.swift:1838-1839, after the AX traversal but before the compact summary is built and returned to the client.

Empirically that is the longest observed wall time for CGWindowListCreateImage on a fully-loaded System Settings window, including the cost of cold-loading ReplayKit. On a warm subprocess (which never happens in this design, since each subprocess is fresh) the call finishes in 80 to 220 ms. Setting the timeout to 5.0 gives 20x headroom for slow disks, contention for the WindowServer, or animation frames mid-transition. If the helper does time out, captureWindowScreenshot returns nil at main.swift:486-489 and the parent simply omits the screenshot path from the compact summary; the tool call still succeeds, the model just does not get a visual confirmation for that one step.

Window selection happens in the parent before the fork, at main.swift:393-433. The parent enumerates CGWindowList for the System Settings PID, filters to layer-zero windows, and scores each by overlap with the AXWindow bounds reported by the most recent traversal. The window with the highest intersection area wins, and its CGWindowID is the first argument passed to the helper. This is necessary because System Settings frequently has a hidden auxiliary window for sheets and toolbars; without bounds-based scoring the helper would sometimes capture the wrong one and the model would see a blank screenshot.

/tmp/macos-use/<timestamp_in_ms>_<tool_name>.png, paired with a sibling .txt file containing the compact AX traversal. Both filenames share the same timestamp prefix so they can be correlated by the model. The directory is created by the parent at the start of each tool call, and old files are not pruned automatically (intentional, so a developer can scrub through a session after the fact). On a project CLAUDE.md the rule is 'don't read entire files into context, use targeted grep searches' against those .txt files.

I checked steipete/macos-automator-mcp, ashwwwin/automation-mcp, CursorTouch/MacOS-MCP, and mb-dev/macos-ui-automation-mcp. None of them ship a separate screenshot binary. Three of them call CGWindowListCreateImage directly from the long-running server process; one shells out to /usr/sbin/screencapture, which works but loses the ability to draw a click-point annotation and is slower than CGWindowListCreateImage when warm. macos-use is the only one I found that pays the cost of a fork-per-screenshot to keep ReplayKit out of the parent. The Package.swift declaration of the second target is at Package.swift:25-29 if you want to grep for it directly.

It marks the exact pixel where the synthetic click landed. The drawing logic is at Sources/ScreenshotHelper/main.swift:50-91: convert the click point from screen coordinates to image-local coordinates using scaleX = imageWidth/windowRect.width and scaleY = imageHeight/windowRect.height, flip Y because CoreGraphics uses bottom-left origin, draw a 15-point arm cross in red (1, 0, 0, 1 RGBA), then add a 10-point ring around it. The point of the annotation is so the model can look at one PNG and instantly answer two questions: is the System Settings window in the right state, and did my click target the right control. Without the crosshair, the second question would require re-deriving the click coordinate from the AX tree.

CGWindowListCreateImage will return nil and the helper will exit 1 with 'error: CGWindowListCreateImage failed for window <id>' on stderr. The parent reads this at main.swift:497-500 and the screenshot path is omitted from the compact summary; the MCP tool call still returns the AX traversal, just without a PNG. To grant the permission, open System Settings, Privacy and Security, Screen Recording, and toggle on the entry for the binary launching the MCP server (typically Claude Desktop, Cursor, or your terminal). After granting, you must quit and relaunch the host application; macOS does not refresh the TCC decision at runtime.

Not via a CLI flag today. The simplest way to skip it is to delete or rename the screenshot-helper binary alongside the server: captureWindowScreenshot checks for it at main.swift:440-443 and returns nil cleanly if it is missing, with a stderr warning. The cost of leaving it on is roughly 120 to 280 ms per tool call (one fork, one CGWindowListCreateImage, one PNG encode, one fwrite) plus a few megabytes of disk per /tmp/macos-use entry. On a fast Mac that is well below the wall time of the AX traversal that already happened, so disabling it rarely meaningfully speeds anything up.

Three reasons. First, screencapture takes 250 to 400 ms cold and posts a shutter sound by default; suppressing the sound requires extra arguments and the latency is still 2x the in-helper path. Second, screencapture cannot draw an annotation, so the parent would have to re-encode the PNG to add the crosshair anyway, doubling the work. Third, screencapture writes to disk but does not return the actual capture rectangle, so the parent cannot match the screenshot back to the traversal window bounds for multi-window apps. The custom helper sidesteps all three by being a thin wrapper around the same CGWindowListCreateImage API the parent would otherwise call, just isolated.