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 covers Claude Code, Cursor, Codex CLI and Claude Desktop, and what to do before pointing this at a machine you care about. → Permissions 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
| What it does | Guide | |
|---|---|---|
| Desktop automation | 35 tools across 13 toolsets: accessibility-tree perception, AX actions, synthetic input, screenshots, apps, windows, the shell, preferences, the filesystem, processes, launchd, the unified log, network, packages, scraping, plan-and-apply | Toolsets and personas |
| Personas | Presets that select toolsets and inject workflow guidance | Toolsets and personas |
| Credentials | The agent signs in to apps and sites without ever being told the secret: the Credentials tool has no read mode, injection requires a secure text field, and the keychain items are removed on every exit path | Credentials |
| Session recording | With transparency.recording_dir set, the whole session goes to one .mov with timeline markers | Session recording |
| Journeys | Declarative UI journeys validated offline, run through the planner, recorded from a human session | Journeys |
| Kill switch | Out-of-band, tiered containment: isolate (pf), kill processes, lock, shut down, with the recording finalised and the credentials revoked first | Security architecture |
Tools
| Toolset | Default | Tools |
|---|---|---|
| screen | yes | Snapshot, Screenshot, DisplayInventory, Recording |
| interaction | yes | Click, Type, Invoke, GetText, Scroll, Move, Shortcut, Wait, WaitFor, MultiSelect, MultiEdit |
| apps | yes | App |
| system | yes | Clipboard, Process, Notification |
| system-admin | Defaults, LaunchdJob | |
| shell | Shell, LaunchExecutable | |
| filesystem | FileSystem | |
| web | Scrape | |
| diagnostics | SystemInfo, Service, UnifiedLog, Network | |
| packages | Package | |
| credentials | Credentials (enabled by --credentials-file) | |
| testing | Assert, CaptureEvidence | |
| planning | Plan, Apply | |
| always | GuardrailStatus, Kill |
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.
on_fail | Effect |
|---|---|
allow | Proceeds; the failure is still recorded |
warn | Proceeds, and the warning rides back with the result so the model sees it |
hold | The call waits on an out-of-band human authoriser and fails closed |
deny | This call is refused, and re-evaluated next time |
kill | The kill switch trips and the containment ladder runs |
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 notarized, in a tarball and Claude Desktop .mcpb.
The release also carries a CycloneDX SBOM and keyless cosign signatures; its
tested cask is published to deploymenttheory/homebrew-tap. The release stays
draft until its assets pass validation. See Getting started
for installation and upgrades.
Documentation
docs/: setup and configuration guides, the security architecture and assessment, the journey vocabulary and the conformance report.
License
MIT, see LICENSE.