Macos MCP Server

@cyanheads/macos-mcp-server Control macOS settings, apps, windows, audio, Music, displays, screenshots, and Focus mode via MCP. STDIO or Streamable HTTP. 14 Tools • 3 Resources

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.

Overview

Control your Mac from an agent: launch, quit, and arrange apps and windows, switch audio and display devices, control Music playback, capture screenshots, work with Finder, send notifications, and toggle Focus mode.

Tools

Resources

Resource data is also accessible via macos_get_info, macos_control_audio (action=list), and macos_manage_displays (action=list).

Capability reference

macos_get_info tool

• Battery level (0–100), charging state, and power source (AC, Battery, UPS); null on desktops with no battery. charging is false when the battery is held at a charge limit (AC attached; not charging) and true while finishing charge
• Wi-Fi association from the Wi-Fi device's link state; the network name is null while connected when macOS withholds it (reading it requires Location Services access for the host app). The name renders in content[] as a code span, so markdown characters in it read back as the name
• Hostname and uptime (from Node's os module), macOS version string (e.g. "15.1")
• Connected display count (0 on a headless Mac)
• A probe that fails leaves its field null and names it in unavailable; nothing is filled in. battery: null with battery absent from unavailable means the Mac has no battery
• No permissions required

macos_check_permissions tool

• Reports Accessibility (every macos_manage_windows action, list included; macos_manage_apps hide and show, and the window_title frontmost reads; the ⌃⌘Q keystroke macos_control_system lock sends before it falls back to the screen saver), Screen Recording (window screenshots), Automation > Finder (macos_manage_finder frontmost_path, get_selection, and trash), and Automation > Music (macos_control_music) from Apple's prompt-free checks: AXIsProcessTrusted, CGPreflightScreenCaptureAccess, and AEDeterminePermissionToAutomateTarget with prompting off
• Each field is true, false, or null when the check can't tell; unknown_reasons names why each null is unknown. Automation > Finder and Automation > Music read null until macOS has asked for consent and while that app isn't running. Notifications is always null: macOS has no prompt-free check for it
• Returns the calling process name (e.g. "ghostty", "node") so you know which process to grant permissions for
• Read-only — no check sends an Apple event to another app, captures the screen, or can show a permission prompt
• Run this first when debugging why another tool is failing

macos_manage_apps tool

• list — 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 by app_name or bundle_id; hidden=true starts in the background
• quit (graceful AppleScript quit) vs. force_quit (SIGKILL, no save prompt)
• hide / show — toggle visibility; requires Accessibility
• quit, force_quit, hide, and show first check that the app is running — resolved by application name the way tell application does ("Visual Studio Code" finds the Code process), without launching it — and return not_running when it isn't
• Typed errors: app_not_found (launch of an app that isn't installed), no_frontmost_app (System Events reports no frontmost process), not_running, accessibility_required

macos_manage_windows tool

• list — all visible windows across apps, with position, size, minimized and fullscreen state (each read from the window's AXMinimized / AXFullScreen attribute, null when it can't be read), and display_index: the display the window overlaps most (the index macos_manage_displays action=list reports), or null when the display frames can't be read or the window overlaps none. Two windows that share a title, and the windows of two processes that share a name, are each listed
• focus, move, resize, move_resize, minimize, fullscreen, close — target by window_title (exact, ignoring case, in any app; when two windows of one app share the title, the frontmost of them) or app_name (that app's frontmost window); window_title takes precedence and app_name is then ignored
• app_name matches a running app by its application name ("Visual Studio Code"), localized name ("Code"), or process name ("firefox"), ignoring case; it is resolved from the running-application list, so no app is launched or sent an Apple event to find it
• move needs x/y, resize needs width/height (both greater than 0), move_resize needs all four
• minimize — minimized: true (the default) minimizes, false restores; it writes the window's AXMinimized attribute only when the window is not already in that state, and succeeds only when the window reads back in the requested state
• fullscreen — fullscreen: true enters, false exits, omitted toggles the window's current state. When the state differs it raises the target window, as focus does, and sets its AXFullScreen attribute (no keystroke, so the window that had keyboard focus is never toggled); it waits up to 4 s for the window to read back in the requested state
• Every action, list included, scripts System Events and requires Accessibility; a denial returns accessibility_required and never reads as "no windows". focus raises the window and brings its app forward; no action launches an app
• Each write finds, changes, and reads back the same window in one script; window.app is the process the window was found under; close returns no window
• Typed errors: not_running (app_name names no running app), window_not_found, accessibility_required, minimize_unsupported and fullscreen_unsupported (the window's AXMinimized / AXFullScreen attribute is missing or not settable, or the window did not reach the requested state within 4 s); an osascript timeout or failure keeps its own error instead of reading as window_not_found

macos_control_volume tool

• get — current output volume (0–100) and mute state of the default output. On an output with no software volume control (many HDMI and DisplayPort displays), level and muted are null and output_device names the device (null when it cannot be identified)
• set — requires level (0–100), muted, or both; level=0 does not mute. On an output with no software control for the requested value it fails with volume_unsupported naming the device and changes nothing
• Always returns current state, with the action echoed
• Typed errors: volume_unsupported; a cancelled call stops the device lookup and settles as cancelled, never as output_device: null

macos_control_audio tool

• list — all input/output devices with an is_default flag; filter with type
• current — default input and output device names
• switch_output / switch_input — case-insensitive partial name match ("MacBook" matches "MacBook Pro Microphone")
• Volume level is separate (macos_control_volume)
• Requires SwitchAudioSource CL