io.github.cyanheads/macos-mcp-server

Finder integration: get the path of the frontmost Finder window, get the current Finder selection, reveal a file or folder in Finder, open a path with a specific app, or move a path to the Trash (recoverable — goes to Trash, not rm). Frontmost path and reveal work without any special permissions. get_selection requires Automation > Finder permission. trash moves files to Trash, not permanent deletion.

Get or set the system output volume level (0–100) and mute state. The get action returns the current level and mute state. The set action accepts level (0–100), muted (true/false), or both. Setting level=0 does not mute — use muted=true for explicit muting.

Post a notification to macOS Notification Center via osascript. The notification appears immediately and uses the calling process's notification settings. Title is required; body, subtitle, and sound are optional. Each call creates a new notification (not idempotent). Do Not Disturb does not suppress notifications sent via osascript.

Manage application lifecycle: list all running user-facing apps, get the frontmost app, launch or activate an app, gracefully quit or force-quit a process, or hide/show an app. Launch activates the app if already running; use hidden=true to start in the background without bringing it forward. Force-quit terminates immediately (SIGKILL) without saving. Hide and show require Accessibility permission.

Get or set the system appearance (dark mode or light mode). The get action returns the current mode. The set action accepts mode="dark", "light", or "toggle". Setting "dark" or "light" is idempotent — calling twice produces the same state. "toggle" flips the current mode on each call.

Reports which macOS permissions relevant to this server are currently granted for the calling process: Accessibility (required for window manipulation, app hide/show), Screen Recording (required for window screenshots), Automation > Finder (required for Finder selection), and Notifications. Use this tool before attempting operations that require elevated permissions to confirm prerequisites without triggering an OS permission prompt.

Get or set Do Not Disturb / Focus mode. The get action is best-effort — macOS 13+ protects the Focus state database and the returned status may be "unknown" on some configurations. The set action requires the built-in "Set Focus" shortcut to exist in the Shortcuts app (present on macOS 12+). Mode names must exactly match configured Focus profiles (e.g. "Do Not Disturb", "Work", "Personal").

Window operations across all visible apps: list all windows with their bounds, focus an app window, move or resize a window, minimize/restore, toggle fullscreen, or close. List and focus do not require Accessibility; all other operations do. When app_name and window_title are both given, window_title takes precedence.

Capture a screenshot of the full screen, a specific display (by 0-based index), a named app window, or a pixel region. Always saves a full-resolution PNG to disk (defaulting to ~/Desktop). Optionally returns a downscaled JPEG preview (max 1024px wide) as base64 for agent visual analysis — keeping response size manageable. Window capture requires Screen Recording permission; all other targets do not.

Returns a snapshot of the current macOS system state: battery level and charging status, power source (AC/Battery), Wi-Fi SSID, hostname, macOS version, uptime in seconds, and connected display count. All fields reflect live system state at the time of the call.

Manage audio device routing: list all input and output devices, get the current default input and output devices, or switch the default input or output device. Device names support case-insensitive partial matching — "MacBook" matches "MacBook Pro Microphone". Volume level control is separate (use macos_control_volume). Requires SwitchAudioSource CLI (brew install switchaudio-osx).

System-level power controls: lock the screen (⌃⌘Q shortcut via Accessibility; falls back to ScreenSaverEngine binary if Accessibility is not granted) or put the display to sleep immediately. Both operations are immediate and user-reversible (wake/unlock with any input).

List connected displays with their current layout (resolution, position, rotation, scaling) and optionally apply a pre-configured display layout by name. Requires displayplacer CLI (brew install jakehilborn/jakehilborn/displayplacer). Layouts are pre-configured in the MACOS_DISPLAY_LAYOUTS environment variable as a JSON object mapping names to displayplacer argument strings. Layout application only accepts named presets — raw displayplacer args are never accepted from the user.