macOS Automation MCP Server: The 355-Line Input Guard That Decides Whether You Can Actually Share A Keyboard With Your Agent

Three are in active distribution as of May 2026. macos-use (mediar-ai/mcp-server-macos-use, Swift, native Accessibility APIs + CGEvent, MIT) is the local one with the input guard described on this page. macos-automator-mcp (steipete/macos-automator-mcp, TypeScript, runs AppleScript and JXA) is a thin wrapper around osascript. mcp-remote-macos-use (baryhuang/mcp-remote-macos-use, Python, VNC + remote synthetic events) targets a Mac you are not sitting at. If you want an agent on the same machine you actually use, macos-use is the only one with a runtime input-arbitration layer; the other two delegate that responsibility to you. If you need remote, mcp-remote-macos-use is the right pick and the input guard is irrelevant. If you only need scripted Apple-app workflows that the AppleScript dictionary already covers (Mail filters, Notes search, Reminders queries), macos-automator-mcp is fine because the model is not racing you on a keyboard.

Eight CGEventTypes are added to the tap mask at InputGuard.swift:116-126: keyDown, keyUp, leftMouseDown, leftMouseUp, rightMouseDown, rightMouseUp, mouseMoved, leftMouseDragged, rightMouseDragged, scrollWheel, flagsChanged. The tap is created at .cghidEventTap with .defaultTap options and headInsert placement (line 131-138), which means it sits in front of every other tap on the system. The callback at line 311 inspects each event's eventSourceStateID. Hardware events have stateID == 0 (line 329); programmatic events posted by CGEvent.post inside the server use .hidSystemState which has a non-zero stateID. The callback returns nil for hardware events (drops them) and Unmanaged.passUnretained(event) for programmatic events (forwards them). The result: while a tool call is in flight, your physical keyboard and mouse do nothing, but the agent's synthesized clicks and keystrokes go through.

Three independent failsafes prevent the lockout. First, the watchdog timer at InputGuard.swift:24 with default watchdogTimeout = 30 seconds calls disengage automatically (line 172-181). Second, plain Esc with no modifiers (keycode 53, checked at line 345) is the explicit kill switch and is the only key that survives the drop filter; the callback returns nil after handleEscPressed runs, so even Esc does not leak into the foreground app. Third, macOS itself disables an event tap if the runloop blocks for too long, which fires .tapDisabledByTimeout in the callback (line 300-305); the server re-enables the tap if it can, but if the process is dead the tap is gone with it. The combination is intentional: you get an opt-in lock that you can unconditionally break.

The tap install itself is the expensive part: CGEvent.tapCreate plus the run-loop source registration plus the synchronous overlay window draw cost roughly 30-60 ms on a 2024-class Mac. The per-event cost in the callback is a single integer field read (eventSourceStateID) plus one keyCode read on keyDown frames; sub-microsecond. The callback runs on the main run loop, so callbacks during a long-running tool call interleave with whatever the agent is doing on the main thread. The disengage at the end of every disruptive tool call (main.swift:1898) costs another ~10 ms because it tears down the run-loop source and hides the overlay window. In normal use you notice the overlay flash on every action; you do not notice the latency.

Because OS-level focus modes do not block your keyboard. Do Not Disturb suppresses notifications. Screen Time blocks apps, not events. There is no Apple-supplied API for 'pause my hardware input for 800 ms while this synthetic click happens, but let the synthetic click through.' The closest primitive Apple ships is the CGEventTap, which is exactly what InputGuard wraps. Doing this correctly requires three things you would not get from a generic OS toggle: filtering by eventSourceStateID so synthetic events still flow, scoping the block to one tool-call duration so the user is not locked out for an entire session, and a kill switch that runs from inside the tap before the event reaches the foreground app. None of those are exposed at any layer above the tap API, which is why the server has to ship its own.

Not as a config flag right now. The engage call at main.swift:1835 fires unconditionally on any tool call where isDisruptive == true (defined at main.swift:1800 as 'every tool except refresh_traversal'). The trade-off is deliberate: the alternative is the user typing into the same focused field as the agent, which will silently corrupt either the user's work or the agent's plan. If you want a 'no guard' mode for narrow cases (you are recording a video and need to overlay your own keystrokes, you are running automation against a different display than your active one), the patch is small (one boolean parameter on the tool input schema, gated at the engage call site) but it is not in the shipped server.

A fullscreen NSWindow at .screenSaver level (so it floats above every app), 15% black tint, with a centered dark pill containing a pulsing orange dot and a single line of text. The pill width is min(720, 50% of screen width); height is 80 px; corner radius is 40 px. The pill text comes from the tool description selected at main.swift:1810-1834, which maps every tool name to a short imperative ('Clicking in app...', 'Typing in app...', 'Pressing Return...'). The window has ignoresMouseEvents = true so it does not intercept clicks visually; only the event tap intercepts them. Code starts at InputGuard.swift:202 (buildAndShowOverlay) and is plain AppKit, so customizing it is a 30-line patch.

claude mcp add macos-use -- npx -y mcp-server-macos-use installs and rebuilds the Swift binary against your Xcode toolchain. After the first tool call you will see two things: the system Accessibility prompt (one-time), and the orange-dot overlay during every subsequent disruptive call. To verify programmatically, tail /tmp/macos-use/tap_status.txt while issuing a tool call (the file is written at InputGuard.swift:154 with the line tap_created: enabled=true at <Date>). Press Esc mid-action and check /tmp/macos-use/esc_pressed.txt for a marker file with the timestamp (written at InputGuard.swift:347). Both files are deliberate breadcrumbs for exactly this kind of verification.