macOS-only. This server controls the local macOS system — it requires the host machine to be running macOS. HTTP transport is supported for completeness, but the practical use case is stdio: run it locally and point your MCP client at it.

Tools

13 tools covering macOS system state, app and window management, audio routing, display control, screenshots, Finder integration, notifications, and Focus mode:

macos_get_info

Returns a live system snapshot with no prerequisites.

• Battery level (0–100), charging state, and power source (AC, Battery, UPS); null on desktops with no battery
• Wi-Fi connection status and SSID
• Hostname, macOS version string (e.g. "15.1.0"), uptime in seconds
• Connected display count

macos_check_permissions

Reports permission status for each capability this server exercises. Run this first when debugging why a tool is failing.

• Accessibility — required for window manipulation (move, resize, minimize, fullscreen, close), app hide/show
• Screen Recording — required for window screenshots (macos_take_screenshot with target=window)
• Automation > Finder — required for macos_manage_finder with action=get_selection
• Notifications — always granted (osascript notifications bypass Do Not Disturb)
• Returns the name of the calling process (e.g. "ghostty", "node") so you know which process to grant permissions for

macos_manage_apps

Manage the lifecycle of user-facing applications.

• list — all running user-facing apps with name, bundle ID, PID, visible, and frontmost flags
• frontmost — name, bundle ID, PID, and frontmost window title of the active app
• launch — open or activate an app by name or bundle ID; hidden=true starts in the background
• quit — graceful quit via AppleScript tell application … to quit
• force_quit — SIGKILL without saving
• hide / show — toggle app visibility; requires Accessibility

macos_manage_windows

Window operations across all visible apps via System Events Accessibility.

• list — all visible windows with app name, title, position, size, minimized state, and display index (0 = primary)
• focus — bring an app or window to the foreground (does not require Accessibility)
• move — reposition a window by top-left coordinate
• resize — change a window's width and height
• move_resize — set position and size in one call
• minimize — minimize to Dock or restore; minimized=true to minimize, false to restore
• fullscreen — toggle fullscreen via ⌃⌘F keystroke
• close — click the close button via Accessibility
• Target by app_name, window_title, or both (window_title takes precedence)
• All mutating actions (everything except list and focus) require Accessibility

macos_control_volume

• get — returns current output volume (0–100) and mute state
• set — accepts level (0–100), muted (true/false), or both; setting level=0 does not mute
• Always returns current state after a set

macos_control_audio

Audio device routing via SwitchAudioSource CLI (brew install switchaudio-osx).

• list — all input and output devices, with is_default flag; filter by type=input|output|all
• current — current default input and output device names
• switch_output / switch_input — change the default device; supports case-insensitive partial name matching ("MacBook" matches "MacBook Pro Microphone")
• Volume level control is separate (macos_control_volume)

macos_control_appearance

• get — returns dark_mode: true/false
• set with mode=dark|light|toggle — dark/light are idempotent; toggle flips on each call

macos_control_system

• lock — locks the screen immediately via ⌃⌘Q (Accessibility); falls back to ScreenSaverEngine binary if Accessibility is not granted
• sleep_display — puts all displays to sleep via pmset displaysleepnow; no permissions required

macos_take_screenshot

Saves a full-resolution PNG to disk; optionally returns a downscaled JPEG preview as base64.

• screen — full screen capture (all displays merged); no Screen Recording required
• display — a specific display by 0-based display_index; no Screen Recording required
• window — a named app window by app_name; requires Screen Recording
• region — a pixel rectangle { x, y, width, height }; no Screen Recording required
• path — custom output path (must be within ~/Desktop, /tmp, or home dir); defaults to MACOS_SCREENSHOT_DIR/<timestamp>.png (falls back to ~/Desktop)
• include_data=true — adds preview (base64 JPEG, max 1024px wide, ~70% quality) + preview_width / preview_height to the response for agent visual analysis

macos_manage_displays

Requires displayplacer CLI (brew install jakehilborn/jakehilborn/displayplacer).

• list — connected display inventory: persistent ID, connection type, resolution, refresh rate, origin, rotation, scaling, enabled state; plus current_config (a displayplacer command string that reproduces the active arrangement)
• apply_layout — activates a named preset from MACOS_DISPLAY_LAYOUTS; layout names are pre-configured in the env var — raw displayplacer args are never accepted from the user

macos_send_notification

Posts to Notification Center via osascript. Does not require notification permission — osascript notifications bypass Do Not Disturb.

• title (required), body, subtitle, sound=true (plays default notification sound)
• Each call creates a new notification; not idempotent

macos_manage_focus

• get — best-effort: reads ~/Library/DoNotDisturb/DB/Assertions.json when accessible; returns status: active|inactive|unknown; unknown is expected on macOS 13+ where the database is SIP-protected
• set — requires the built-in "Set Focus" shortcut to exist in Shortcuts.app (present by default on macOS 12+); mode must match a configured Focus profile exactly (e.g. "Do Not Disturb", "Work"); enabled defaults to true

macos_manage_finder

Finder integration via osascript and open.

• frontmost_path — POSIX path of the active Finder window, or null when no window is open; no permissions required
• get_selection — POSIX paths of selected items; requires Automation > Finder permission
• reveal — highlight a path in Finder (open -R path)
• open_with — open a path with a named app (open -a AppName path)
• trash — moves a path to the Trash (recoverable); not a permanent delete

Resources