macOS MCP Server

macos-mcp-server

A Model Context Protocol server that bridges AI agents to the macOS desktop: the accessibility tree, synthetic mouse and keyboard input, screenshots, window and application control, the shell, preferences, launchd, processes, the filesystem and web scraping. No computer-vision model is required: the agent perceives the UI through the accessibility tree, the way assistive technology does.

It is the macOS counterpart of windows-mcp-server: the same 35 tools, toolsets, personas, policy documents and journeys. What separates both from a plain automation bridge is that every agent action is gated on live device posture, the agent's network egress is constrained, and both are recorded in a tamper-evident audit chain the agent cannot switch off.

• Device policy engine: every tool call, resource read and prompt fetch is evaluated against live device signals (MDM enrolment, Platform SSO, boot security, FileVault, SIP, the sealed system volume) before it runs, and refused, warned or contained by policy. Rules match by tool, toolset or annotation, so a screenshot is not gated like a shell command. → Policy configuration
• Egress allowlist: a loopback proxy admits only the domains you declare, optionally backed by pf rules so the console user, or the whole machine, cannot go around it. → Egress
• Tamper-evident transparency: a hash-chained audit log (keyed, anchored to the unified log), heartbeat, rug-pull detection, whole-session recording, evidence bundles and an out-of-band tiered kill switch. None of it is agent-disableable. → Security architecture

**Several tools (Shell, LaunchExecutable, Defaults, LaunchdJob, FileSystem,

Process, App) have full user-level system access with no sandboxing.** That

is the design. Run untrusted workloads in a guest, see

VM isolation, and read SECURITY.md

for what is and is not in scope as a vulnerability.

Requires macOS 27 or later on Apple silicon. Apple does not support Intel Macs on macOS 27.

---

Quick start

brew install deploymenttheory/tap/macos-mcp-server

macos-mcp-server permissions request # grant Accessibility and Screen Recording once SERVER="$(command -v macos-mcp-server)" codex mcp add macos -- "$SERVER" stdio --persona business-user

Or, for Claude Code:

claude mcp add --scope user macos -- "$SERVER" stdio --persona business-user

For Claude Desktop, install the .mcpb from the latest GitHub release under Settings > Extensions > Advanced settings > Install Extension. It contains the signed server binary and requests the required macOS grants on first launch.

Any other local MCP client can launch the binary with the stdio subcommand:

{

"mcpServers": { "macos": { "command": "/absolute/path/from/command-v/macos-mcp-server", "args": ["stdio", "--persona", "first-line-support"] } } }

→ [Getting started](docs/getting-started.md) covers Claude Code, Cursor, Codex CLI and Claude Desktop, and what to do before pointing this at a machine you care about. → [Permissions](docs/permissions.md) explains the privacy grants and why the signing identity matters.

Not sure this is for you? If you have to approve it on a fleet, read Deciding to deploy this. If you have a job to do, see the walk-throughs for a UI regression suite or a first-line support queue.

---

Features

---

Tools

Four names differ from the Windows server because they name a different subsystem: Defaults (Registry), Shell (PowerShell), LaunchdJob (ScheduledTask) and UnifiedLog (EventLog). Everything else, including the journey vocabulary, is identical.

Resources: macos://desktop/snapshot, macos://desktop/displays, macos://session/recording, macos://system/info. Prompts: rpa-journey, triage-support-issue, capture-evidence.

macos-mcp-server personas                       # first-line-support, qa-test-engineer, business-user

macos-mcp-server stdio --persona qa-test-engineer macos-mcp-server stdio --toolsets screen,interaction,apps --read-only

What cannot be automated, by design

The login window, the lock screen, Touch ID and password sheets, TCC consent dialogs, and the contents of secure text fields. These are the system's own trust boundaries; the server does not try to cross them.

---

Security

📐 Security architecture ·

📄 Policy configuration ·

🔎 Security assessment

A policy engine sits between the MCP client and the tools:

MCP client ──▶ audit ──▶ rug-pull ──▶ policy engine ──▶ tool handler

│ device signals

macos-mcp-server stdio --policy-config "/Library/Application Support/MacOSMCP/policy.json"

With no `--policy-config` the built-in default applies: the engine is present, every declared signal is evaluated and every verdict recorded, and nothing is refused. Adopting the engine cannot break a working deployment before its policy is written.

macos-mcp-server policy validate --policy-config policy.json   # document + signal ids; exit 1

macos-mcp-server policy check --policy-config policy.json # this device now; exit 2 if not admitted macos-mcp-server policy explain --policy-config policy.json --tool Shell macos-mcp-server policy test policy/examples/tests/*.json # fixtures, in CI macos-mcp-server audit verify "/Library/Application Support/MacOSMCP/audit" macos-mcp-server evidence bundle --dir ... --session 20261007-120000

Seven starting points ship in policy/examples/: audit.json (adopt first, refuses nothing), secure.json, enterprise.json, locked-down.json, egress.json, dual-control.json and evidence-export.json.

Trust model

The local device signals are auditable defence-in-depth, not a hard boundary: root can spoof them, and privacy grants are keyed on the signing identity rather than on a hash of the binary. The containment layers raise the cost of, and record, in-session compromise; pair them with MDM, Gatekeeper and notarization, Platform SSO and Conditional Access, and FileVault. Two macOS specifics are worth knowing before trusting a posture: pf filters by socket owner, so the "scoped" egress tier bounds the console user rather than named applications, and the posture signals are Windows-named with a documented macOS reading. Both are spelled out in the assessment.

---

MCP conformance

Every PR runs the required MCP spec gate against the latest published MCP revision. It captures the product's actual advertised surface and raw wire responses, checks the definitions and safe method calls against the published schema, and fails if a newer revision needs assessment. The check covers the features this server implements, without assigning a percentage for optional features it does not implement. See MCP spec gate.

---

Architecture

cmd/macos-mcp-server     cobra/viper CLI (stdio transport; conformance-serve only behind a tag)

internal/macmcp RunStdio orchestration, probes, credentials, permissions, policy ops internal/macdesktop the engine: accessibility tree, CGEvent input, ScreenCaptureKit screenshots, screencapture recording, keychain, launchd, log, network internal/macguard pf egress enforcer, networksetup system proxy, containment actuator internal/clirunner argv-only process runner with a rebuilt environment internal/acceptance the tart-lab acceptance suite (MACOS_MCP_ACC=1) pkg/macos tool definitions, toolsets, personas, resources, prompts mcp-server-core (imported) inventory, toolkit, surface, guardrail runtime, journeys, schema loader, conformance fixtures and host agentweave-harness (imported) policy engine, audit chain, rug-pull, kill switch, egress proxy policy/examples starting-point policy documents, with fixtures under tests/ schema/ vendored MCP protocol schemas, one directory per revision

All accessibility, event and AppKit work runs on the process main thread through Desktop.Do; tool handlers receive their dependencies from the request context via receiving middleware.

---

Development

make check              # vet, test, lint

make sign-dev # a stable local signing identity so TCC grants survive rebuilds make conformance # validate the implemented product behavior make release-snapshot # goreleaser dry run, unsigned

Releases are cut by release-please and built by release.yml: one arm64 binary, Developer ID signed and not