# Reported issues for macos-mcp-server

Pod holds 13 of 13 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [macos-mcp-server](/mcp/macos-mcp-server).

## Most discussed

### bug(multiple tools): raw CLI command strings leak into error messages

### Server version

0.1.1

### mcp-ts-core version

0.9.9

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

Several tool handlers surface raw `execFile` error messages directly to the agent, leaking internal CLI invocations (command path + arguments). The errors also lack `reason` codes and recovery hints, making them non-actionable.

Affected cases:

| Tool | Input that triggers it | Leaked command |
|:-----|:--------

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/4) · 2026-05-25 · closed · 2 comments

### bug(macos_take_screenshot): target=window always fails on macOS 26.1 — ObjC.deepUnwrap(CGWindowList) returns null entries

### Server version

0.1.1

### mcp-ts-core version

0.9.9

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`macos_take_screenshot` with `target=window` always returns `window_not_found` even for apps that are clearly running and have visible windows. Tested with Finder, Code (VS Code), and ghostty — all fail.

The window-capture flow uses JXA with `ObjC.import('CoreGraphics')` and `$.CGWindowListCopyWindowInfo($.kCGWi

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/3) · 2026-05-25 · closed · 2 comments

### bug(macos_manage_windows): minimize action fails with "Can't convert types" on macOS 26.1

### Server version

0.1.1

### mcp-ts-core version

0.9.9

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`macos_manage_windows` with `action=minimize` always fails with an `osascript` execution error, regardless of the target app. Tested with Finder and ghostty — both return the same error.

The `minimize` case executes `win.minimized = <bool>` via the `buildFindWindowScript` helper, which sets the `minimized` prope

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/2) · 2026-05-25 · closed · 2 comments

### bug(macos_control_audio): SwitchAudioSource -f dict flag not supported in v1.2.2, breaking list and switch_output/switch_input

### Server version

0.1.1

### mcp-ts-core version

0.9.9

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`macos_control_audio` with `action=list`, `switch_output`, or `switch_input` always returns an `InternalError` (`-32603`). The `macos://audio/devices` resource also fails with the same error.

`AudioService.listDevices` calls `SwitchAudioSource -a -f dict` to get structured output, but the `-f` flag (format selec

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/1) · 2026-05-25 · closed · 2 comments

### bug(macos_get_info): fully-charged battery on AC renders as "on battery"

`macos_get_info` renders `— on battery` for a machine that is fully charged and running on AC, contradicting the `Power Source: AC` line printed directly beneath it.

## Reproduce

On a laptop plugged in and topped up (`pmset -g batt` reports `charged`, not `charging`):

```
pmset -g batt
Now drawing from 'AC Power'
 -InternalBattery-0 (id=22675555)	100%; charged; 0:00 remaining present: true
```

Call `macos_get_info` with no arguments. `content[0]`:

```
### Power
**Battery:** 100% — on batter

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/6) · 2026-08-22 · closed · 1 comment

### bug(services): silent probe fallbacks report failures as observed values

Two helpers swallow failures and return placeholder values that are indistinguishable from real observations, so a failed probe is reported to the caller as fact.

## `runSafe`

`src/services/system-info/system-info-service.ts` wraps every probe:

```ts
async function runSafe(cmd: string, args: string[]): Promise<string> {
  try {
    const r = await execFile(cmd, args, { timeout: 10_000 });
    return (r.stdout ?? '').trim();
  } catch {
    return '';
  }
}
```

Each caller then substitutes a 

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/13) · 2026-08-22 · open · 0 comments

### feat(tools): display_index and layout_name are unobtainable, and displays[].type examples don't match reality

Two tool parameters take identifiers that no tool in the server can produce, and one output field's documented examples do not match the values it returns. All three are cases where a strong model guesses correctly and a weaker one cannot.

## `display_index` has no source

`macos_take_screenshot` takes a 0-based `display_index`, and its `display_not_found` recovery says:

> Call macos_manage_displays with action=list to see available displays.

That list returns persistent UUIDs and no index fi

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/12) · 2026-08-22 · open · 0 comments

### bug(tools): missing required arguments classified three incompatible ways, one with a misleading reason

Across the tool surface, a missing conditionally-required argument produces three mutually incompatible outcomes. One of them hands the caller a typed reason that describes a different problem than the one that occurred.

## The three behaviors

**1. Silent success.** `macos_control_volume {"action":"set"}` does nothing and reports success. Filed separately as #8.

**2. Unclassified `InternalError`.** `macos_manage_windows` move, `macos_manage_displays` apply_layout, `macos_manage_focus` set, an

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/11) · 2026-08-22 · open · 0 comments

## Most recent

### bug(macos_get_info): Wi-Fi reported disconnected when Location Services gates the SSID

`macos_get_info` and `macos://system/info` report `wifi: {ssid: null, connected: false}` on a machine that is associated with a network. The server is collapsing "cannot read the SSID" into "not connected".

## Reproduce

Call `macos_get_info` on a Mac joined to a Wi-Fi network:

```json
"wifi": { "ssid": null, "connected": false }
```

Ground truth on the same machine:

```
$ system_profiler SPAirPortDataType
  Current Network Information:
    PHY Mode: 802.11ax
    Network Type: Infrastructure

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/10) · 2026-08-22 · open · 0 comments

### bug(macos_manage_finder): trash on a nonexistent path throws InternalError instead of path_not_found

`macos_manage_finder action=trash` with a path that does not exist fails as an unclassified `InternalError` carrying the raw AppleScript, instead of the `path_not_found` the tool declares. The `reveal` action pre-checks the same path and returns the typed error correctly.

## Reproduce

```json
{"action": "trash", "path": "/zz/no/such/path/qx.txt"}
```

Returns `-32603 InternalError`:

```
osascript failed: 29:72: execution error: Finder got an error: Handler can't handle objects of this class. 

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/9) · 2026-08-22 · open · 0 comments

### bug(macos_control_volume): set with no level and no muted silently no-ops and reports success

`macos_control_volume action=set` called with neither `level` nor `muted` does nothing and reports success. The result is indistinguishable from a set that took effect.

## Reproduce

```json
{"action": "set"}
```

Returns, with no `isError`:

```json
{"level": 56, "muted": false}
```

Nothing was changed. `56` is the volume that was already in effect.

## Cause

The handler falls through all three branches without writing anything, then reads the current state back and returns it as the result.

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/8) · 2026-08-22 · open · 0 comments

### bug(macos_manage_apps): quit reports success for an app that isn't running

`macos_manage_apps action=quit` reports `success: true` for an application that is not running. The sibling actions `force_quit`, `hide`, and `show` all pre-check the process list and correctly return `not_running` for the same input.

## Reproduce

```json
{"action": "quit", "app_name": "ZzNonexistentAppQx"}
```

Returns, with no `isError`:

```json
{"action": "quit", "success": true, "app_name": "ZzNonexistentAppQx"}
```

The same name through `force_quit`, `hide`, or `show` returns `-32001` w

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/7) · 2026-08-22 · open · 0 comments

### feat(macos_control_music): add Apple Music transport control tool

The server controls system output volume (`macos_control_volume`) and audio device routing (`macos_control_audio`), but has no playback control for the Apple Music app. Add a `macos_control_music` tool that drives Music.app via AppleScript (`tell application "Music"`) through the existing `osascript-service` — rounding out the macOS media surface alongside volume and audio.

## Proposal

A single `macos_control_music` tool exposing transport verbs and now-playing reads for the Apple Music app. P

[Read the thread](https://github.com/cyanheads/macos-mcp-server/issues/5) · 2026-06-15 · open · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/cyanheads/macos-mcp-server/issues).