macos-use: The MCP Server That Locks Your Keyboard While the AI Drives

macos-use (mcp-server-macos-use) is a Model Context Protocol server written in Swift that gives MCP-compatible AI clients (Claude Code, Claude Desktop, Cursor, VS Code) the ability to control any macOS application. It exposes six tools (open, click, type, press key, scroll, refresh traversal) and drives the OS through Apple's native AXUIElement and CGEvent APIs rather than screenshots. Source: github.com/mediar-ai/mcp-server-macos-use.

They stop working. The moment a disruptive tool fires (open, click, type, press key, scroll), main.swift:1696 calls InputGuard.shared.engage(), which creates a CGEventTap on .cghidEventTap and sets an event mask that includes keyDown, keyUp, leftMouseDown, leftMouseUp, mouseMoved, scrollWheel and flagsChanged. The tap returns nil for every hardware event, which suppresses it. The server's own CGEvent.post() calls go through because they carry a non-zero sourceStateID. The lockout lasts only as long as the action takes, plus a 200ms grace period afterward.

Press Esc with no modifiers held. The CGEventTap callback in InputGuard.swift watches for keyCode 53 with an empty modifier-mask intersection. When it sees that, it writes /tmp/macos-use/esc_pressed.txt, sets the internal _cancelled flag, suppresses the Esc event itself, and disengages the tap. main.swift:1708, 1721, 1728, and 1734 all call InputGuard.shared.throwIfCancelled() between sub-steps, so cancellation lands before the next click or keystroke goes out. The catch site at main.swift:1847 disengages cleanly and restores both your cursor position and your previously-frontmost app.

InputGuard ships with a DispatchSource watchdog timer set to 30 seconds (InputGuard.swift, watchdogTimeout). When it fires, the timer handler calls disengage() unconditionally, which removes the run-loop source, invalidates the CFMachPort, and orderOut()s the overlay window. There is no path where the lockout outlives the watchdog. The number is configurable on the InputGuard.shared instance if you fork the server.

A fullscreen transparent NSWindow at .screenSaver level with a 15% black tint. Centered on the main screen is a pill that is 720pt wide (capped at 50% of screen width), 80pt tall, with a corner radius of pillHeight/2 and a near-black NSColor(white: 0.08, alpha: 0.92) background. Inside the pill: a 16pt orange dot (NSColor.systemOrange) running an opacity CABasicAnimation between 1.0 and 0.3 over 0.8s, autoreversed and repeating forever. Next to the dot, white 20pt semibold system font on a single truncating line that says "AI: Clicking in app… — press Esc to cancel". The window has ignoresMouseEvents set to true, so it does not steal interaction from anything underneath.

main.swift:1672-1676 saves the current NSEvent.mouseLocation (in screen-y-flipped coordinates) before the action runs. main.swift:1767-1771 posts a synthetic .mouseMoved CGEvent back to that exact CGPoint after the action completes, on .cghidEventTap. The cancellation path at 1852 does the same thing on Esc, so even when you abort mid-action your pointer ends up where you left it instead of wherever the agent's last click landed. main.swift:1671 also captures NSWorkspace.shared.frontmostApplication and reactivates it at 1779, so focus returns to the app you were using.

Source-state ID. Hardware HID events carry sourceStateID == 0. CGEvent.post() calls from the SDK go out on the .hidSystemState source, which produces a non-zero state ID. The free-function callback at the bottom of InputGuard.swift reads CGEventField.eventSourceStateID on every event and short-circuits with Unmanaged.passUnretained(event) if it is non-zero. That is the entire trick. It is also what makes the Esc-detection unambiguous: the keyDown for an SDK-injected key has a non-zero state ID and is allowed through without being checked for keyCode 53.

Yes, the host application that spawns the server (Claude Desktop, Cursor, your terminal, VS Code) needs Accessibility in System Settings > Privacy & Security > Accessibility. Without it, both AXUIElement traversal and CGEventTap creation fail. InputGuard.swift logs an explicit "check Accessibility permissions" hint to stderr when CGEvent.tapCreate returns nil, and the engage() call falls through harmlessly so the agent can still report the failure instead of silently locking your input.

The other two MCP servers also drive macOS, but neither blocks your input or shows an overlay while a tool is running. mcp-remote-macos-use targets remote control over screen-sharing and uses a credentials-driven flow. MacOS-MCP exposes screenshot-style tools. macos-use is the only one that ships an InputGuard, a watchdog timer, and an Esc-throws-mid-step contract, which matters when you give an AI write-access to GUI apps and want a hard stop. Source-level proof lives at Sources/MCPServer/InputGuard.swift in this repo.

Six. macos-use_open_application_and_traverse (opens an app by name, bundle id, or path), macos-use_click_and_traverse (click + optional type + optional key, supports element-by-text search), macos-use_type_and_traverse (type into focused field), macos-use_press_key_and_traverse (key + modifiers), macos-use_scroll_and_traverse (deltaX, deltaY in lines), and macos-use_refresh_traversal (read the AX tree without acting). Every tool except refresh is treated as disruptive in main.swift:1667 and goes through the input-guard engage/disengage cycle. Every tool returns a compact summary plus a path to a flat-text accessibility tree dump in /tmp/macos-use/.