.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/macos-mcp-server</h1> <p><b>Control macOS system settings, apps, windows, audio, displays, screenshots, and Focus mode via MCP. STDIO or Streamable HTTP.</b> <div>13 Tools • 3 Resources</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

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, 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), and Automation > Finder (macos_manage_finder frontmost_path, get_selection, and trash) 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 reads null until macOS has asked for consent and while Finder 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 CLI (brew install switchaudio-osx); typed errors device_not_found, switchaudio_unavailable

macos_control_appearance _tool

• get — returns dark_mode: true/false, with the action echoed
• set requires mode: "dark" | "light" | "toggle" — dark/light are idempotent, toggle flips on each call
• Scripts System Events; typed error accessibility_required when Automation > System Events is denied

macos_control_system _tool

• lock — ⌃⌘Q via Accessibility; falls back to the ScreenSaverEngine binary when Accessibility isn't granted (a cancelled call never falls back)
• sleep_display — pmset displaysleepnow; no permissions required
• Both operations are immediate and reversible with any input (wake/unlock)

macos_take_screenshot _tool

• target: screen (the main display only, the one with the menu bar), display (0-based integer display_index, default 0: the index macos_manage_displays action=list reports), region (pixel rect, width/height greater than 0) — no Screen Recording required; window (by app_name, matched like macos_manage_windows: application name, localized name, or process name, ignoring case; captures that app's frontmost on-screen window) requires Screen Recording. When the Screen Recording check can't tell, the window capture still runs and notice says why
• Always saves a full-resolution PNG. Omitting path (or passing "") writes a new screenshot-<timestamp>.png in MACOS_SCREENSHOT_DIR (~/Desktop when unset), adding -2, -3, … rather than replacing a file. A custom path must end in .png (any case); ~/ expands to the home directory; its directory must exist and, with symlinks resolved, lie inside MACOS_SCREENSHOT_DIR, /tmp, or the home directory. The returned path is the resolved one (a /tmp path reports under /private/tmp)
• Never replaces an existing entry: a path that already exists fails with path_exists unless overwrite: true, which replaces only the regular .png file found at path when the call checks it (never a symbolic link or directory). An entry created at path after that check, or put in that file's place, is never replaced and fails with path_exists
• Every call settles within 55 s of its start, the app_name lookup included: past that it fails as a Timeout (-32004) and writes nothing. A cancelled request writes nothing either
• include_data=true returns a JPEG preview, longer side at most 1024 px (a smaller capture keeps its own size), quality 70: as the first content[] block (image/jpeg) and as base64 preview plus preview_width/preview_height in structuredContent
• width/height (and the preview's) are read from the image file headers
• Typed errors: screen_recording_required, window_not_found (an app that is not running, or one with no on-screen window; an osascript timeout or failure during the window lookup keeps its own error), display_not_found, path_not_writable (also a directory that cannot be resolved or searched, an over-long one included), path_exists; a path not ending in .png, holding U+0000, or whose file name or full resolved path is longer than the file system allows (255 bytes per name, 1024 for the whole path) is rejected as -32602 with reason invalid_arguments

macos_manage_displays _tool

• list — per display: index (0-based position in NSScreen.screens; the display_index macos_take_screenshot and macos_manage_windows use; null for a display with no NSScreen entry, such as a disabled one), persistent ID, type ("MacBook built in screen" or "<N> inch external screen"), resolution, refresh rate ("N/A" when macOS reports none), origin, rotation, scaling, and enabled state (also true for a display mirroring another); plus current_config (a displayplacer command that reproduces the active arrangement) and layouts (the names configured in MACOS_DISPLAY_LAYOUTS, [] when none). When MACOS_DISPLAY_LAYOUTS is invalid, list still succeeds, omits layouts, and its notice names the variable. When the NSScreen read fails, index is omitted and notice says why; that includes a read that waited 15 s for concurrent System Events enumerations to finish
• apply_layout — activates a named preset from MACOS_DISPLAY_LAYOUTS (one of the names list returns as layouts); raw displayplacer args are never accepted from the caller. An invalid MACOS_DISPLAY_LAYOUTS fails apply_layout as layouts_invalid (ConfigurationError), never layout_not_found
• Requires displayplacer CLI (brew install displayplacer); typed errors displayplacer_not_found, displayplacer_output_unrecognized, layout_not_found, layouts_invalid
• A failed displayplacer run (non-zero exit, signal, timeout) fails the call instead of returning what it printed; a display block missing a line whose value the listing returns, or a listing missing the arrangement command, fails as displayplacer_output_unrecognized. displayplacer 1.3.0 and 1.4.0 are both read

macos_send_notification _tool

• title required; body, subtitle, and sound=true (default notification sound) are optional
• Each call creates a new notification — not idempotent
• No permission required to post; an active Focus such as Do Not Disturb silences it unless that Focus allows the posting app

macos_manage_focus _tool

• get — best-effort; reads ~/Library/DoNotDisturb/DB/Assertions.json and returns status: "active" | "inactive" | "unknown"; unknown (with a reason) when that file cannot be read or parsed, which can happen when the server process is not allowed to read it; a cancelled call settles as cancelled, never as unknown
• set — runs a shortcut named "Set Focus" from your Shortcuts library and passes it {"mode": …, "enabled": …} as JSON input. The shortcut is not built in: create it with Get Dictionary from Input feeding the Set Focus action. mode must exactly match a configured Focus name, including case (e.g. "Do Not Disturb", "Work"); enabled defaults to true. The result echoes mode and enabled; success: true means the shortcut finished without error (the Focus state is not read back)
• Typed errors: shortcuts_unavailable (shortcuts CLI missing, or no shortcut named "Set Focus"), shortcut_failed (the shortcut exited with an error; carries its error text). A shortcut still running after 15 s is stopped and reported as a Timeout error; a cancelled call stops the run and settles as cancelled

macos_manage_finder _tool

• frontmost_path — POSIX path of the active Finder window, or null when none is open; a cancelled call settles as cancelled, never as null
• get_selection — POSIX paths of selected items
• reveal (open -R), open_with (open -a <App>, or the default app when app_name is omitted), trash (moves to Trash — recoverable, never a permanent delete)
• open_with and trash check that the path exists before calling open or Finder
• frontmost_path, get_selection, and trash script Finder and require Automation > Finder permission; reveal and open_with need none
• Typed errors: finder_not_open, path_not_found, app_not_found (unknown open_with app), trash_refused (Finder declined an existing item — locked, in use, or no Trash on the volume), accessibility_required

macos://system/info _resource

• Current macOS system snapshot as application/json — battery, power source, Wi-Fi association and network name, hostname, version, uptime, display count, and unavailable
• Same data is also reachable via macos_get_info

macos://audio/devices _resource

• All audio input and output devices, including which is the current default, as application/json
• Requires SwitchAudioSource CLI
• Same data is also reachable via macos_control_audio (action=list)

macos://displays _resource

• Connected display inventory — index, persistent IDs, type, resolution, origin, rotation, scaling, enabled state, plus current_config — as application/json; carries notice (and no index) when the NSScreen read fails
• Requires displayplacer CLI
• Same data is also reachable via macos_manage_displays (action=list)

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

macOS-specific:

• osascript service wraps both JXA (runJxa) and AppleScript (runAppleScript) with a configurable timeout
• SwitchAudioSource and displayplacer integrations are optional dependencies, found on PATH, in /opt/homebrew/bin, or in /usr/local/bin on every call — the affected tools fail with ServiceUnavailable and an install instruction when no location has the CLI
• macOS system binaries (osascript, screencapture, sips, pmset, networksetup, system_profiler, …) run by absolute path, so the host PATH never decides which binary runs
• screencapture writes into a private directory beside the destination and the PNG is placed without replacing anything the call did not check; sips makes the JPEG preview; image sizes come from the PNG/JPEG headers
• pmset for battery, networksetup + ifconfig for Wi-Fi, sw_vers for version, system_profiler -json SPDisplaysDataType for displays, Node's os for hostname and uptime
• Permission-first design — macos_check_permissions reports exactly which process needs which grant before a tool hits Forbidden

Agent-friendly output:

• Permission errors carry the accessibility_required reason and grant instructions for the permission actually denied — Privacy & Security > Accessibility, or Privacy & Security > Automation for the named app
• A missing per-action argument (set without mode, quit without app_name), or text no AppleScript literal can carry (U+0000, an unpaired surrogate), is rejected before anything runs, as -32602 with reason invalid_arguments and a hint naming what to send; each multi-action tool advertises the per-action requirements in its inputSchema
• Errors carry the failing program's own error text, never its command line or script source
• Optional CLI dependencies surface ServiceUnavailable with the exact brew install command needed
• macos_manage_windows reports display_index (the display a window overlaps most, or null when unknown) on every window so agents can reason about multi-monitor layouts
• macos_take_screenshot separates the full-resolution disk write from an optional preview, sent as an image content block and as base64 in structuredContent so both surfaces carry it

Getting started

This server is local-only — it controls the macOS system it runs on. Use STDIO transport with your MCP client.

Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "macos-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/macos-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "macos-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/macos-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• macOS 13 (Ventura) or higher.
• Bun v1.4.0 or higher (or Node.js v24+).
• Optional: SwitchAudioSource for audio routing (brew install switchaudio-osx).
• Optional: displayplacer 1.3.0 or 1.4.0 for display management (brew install displayplacer).

Either optional CLI works from Homebrew on Apple Silicon (/opt/homebrew/bin) or Intel (/usr/local/bin), or from anywhere on PATH.

Some tools require macOS permissions granted to the terminal or MCP host app:

Use macos_check_permissions to check current status before running permission-gated operations.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/macos-mcp-server.git

1. Navigate into the directory:

cd macos-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env
# edit .env if you want to set MACOS_SCREENSHOT_DIR or MACOS_DISPLAY_LAYOUTS

Configuration

See .env.example for the full list of optional overrides.

Display layout example:

# Get the current displayplacer command for your setup:
displayplacer list

# Then configure named layouts in your env:
MACOS_DISPLAY_LAYOUTS='{"office":"\"id:1234 res:2560x1440 hz:60 color_depth:8 scaling:on origin:(0,0) degree:0\" \"id:5678 res:1920x1080 hz:60 color_depth:8 scaling:on origin:(2560,0) degree:0\""}'

Each screen gets its own quoted segment, the form displayplacer list prints its arrangement command in; a layout value without quoted segments reaches displayplacer as a single argument. macos_manage_displays action=list returns current_config with the same per-screen quoted segments, and returns the configured names as layouts.

Running the server

Local development

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio

# Run checks
bun run devcheck   # Lint, format, typecheck, security, changelog sync
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging; no console calls
• Read actual system/CLI state and never fabricate it — return null or unknown when the OS can't answer (e.g. battery on desktops, Focus status when the Focus state file cannot be read) rather than guessing
• Services are singletons initialized in createApp() and accessed via get*Service() accessors

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.