macos-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">

[![Version](https://img.shields.io/badge/Version-0.1.5-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/macos-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/macos-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun->=1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/macos-mcp-server/releases/latest/download/macos-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=macos-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvbWFjb3MtbWNwLXNlcnZlciJdfQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22macos-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fmacos-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</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.

---

## Tools

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

| Tool | Description |
|:-----|:------------|
| `macos_get_info` | System snapshot: battery level and charging status, power source, Wi-Fi SSID, hostname, macOS version, uptime, and display count |
| `macos_check_permissions` | Reports Accessibility, Screen Recording, Automation > Finder, and Notification status for the calling process |
| `macos_manage_apps` | List, launch, quit, force-quit, hide, or show applications |
| `macos_manage_windows` | List, focus, move, resize, move_resize, minimize, fullscreen, or close windows |
| `macos_control_volume` | Get or set system output volume (0–100) and mute state |
| `macos_control_audio` | List audio devices, get current defaults, or switch the default input/output device |
| `macos_control_appearance` | Get or set dark/light mode |
| `macos_control_system` | Lock the screen or put the display to sleep |
| `macos_take_screenshot` | Capture full screen, display, named app window, or pixel region; saves PNG; optional base64 JPEG preview |
| `macos_manage_displays` | List connected displays and apply named display layout presets |
| `macos_send_notification` | Post a notification to macOS Notification Center |
| `macos_manage_focus` | Get or set Do Not Disturb / Focus mode |
| `macos_manage_finder` | Frontmost path, current selection, reveal, open with app, or move to Trash |

### `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

| Type | Name | Description |
|:-----|:-----|:------------|
| Re