macOS MCP Server

io.github.deploymenttheoryPublished by GitHub account deploymenttheoryv0.2.1Updated Oct 24, 2026

Local macOS 27 desktop automation through MCP on Apple silicon.

VerifiedSTDIODesktop onlyBrowser AutomationDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

Local MCP server that lets an AI agent perceive and control the macOS desktop through the accessibility tree, input, screenshots, shell and files.

What you can do
  • Perceive and capture the screen: accessibility-tree snapshots, screenshots, display inventory and session recording
  • Drive the UI: click, type, invoke, read text, scroll, move, shortcuts, waits and multi-select edits
  • Control apps, windows, clipboard, processes and notifications
  • Administer the system: preferences, launchd jobs, shell commands, executable launching, filesystem access, packages, unified log, network and services
  • Scrape web content, run declarative plan-and-apply journeys, and assert or capture evidence for testing
  • Gate every call through a device policy engine with an egress allowlist, hash-chained audit log and kill switch
When to use it
Use it when an agent must operate a real macOS desktop on Apple silicon: UI regression tests, first-line support triage, or scripted workflows that need apps, windows, shell and files. It is aimed at machines you control and can govern with policy, not at untrusted workloads.
Requirements
macOS 27 or later on Apple silicon. Installed as a Homebrew cask, a signed .mcpb extension for Claude Desktop, or a binary launched with the stdio subcommand from any local MCP client. Accessibility and Screen Recording grants must be approved once; a persona and optional toolsets, read-only mode, policy config and credentials file are passed as command-line flags. No environment variables or headers are declared.
Before you install
Several tools (Shell, LaunchExecutable, Defaults, LaunchdJob, FileSystem, Process, App) have full user-level system access with no sandboxing by design; run untrusted workloads in a guest VM. With no policy config the built-in default refuses nothing. The kill switch can isolate the network, kill processes, lock or shut down the machine. The Credentials tool handles keychain secrets, and session recording writes the whole session to a video file. Device posture signals are defence-in-depth…

Installation

In SourceWeft

  1. Open macOS MCP Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

macos-mcp-server

[Spec compliance]

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

sh
brew install deploymenttheory/tap/macos-mcp-servermacos-mcp-server permissions request      # grant Accessibility and Screen Recording onceSERVER="$(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:

json
{  "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 doesGuide
Desktop automation35 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-applyToolsets and personas
PersonasPresets that select toolsets and inject workflow guidanceToolsets and personas
CredentialsThe 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 pathCredentials
Session recordingWith transparency.recording_dir set, the whole session goes to one .mov with timeline markersSession recording
JourneysDeclarative UI journeys validated offline, run through the planner, recorded from a human sessionJourneys
Kill switchOut-of-band, tiered containment: isolate (pf), kill processes, lock, shut down, with the recording finalised and the credentials revoked firstSecurity architecture
MCP conformanceImplemented protocol behavior checked against the latest published spec on every PRMCP compliance

Tools

ToolsetDefaultTools
screenyesSnapshot, Screenshot, DisplayInventory, Recording
interactionyesClick, Type, Invoke, GetText, Scroll, Move, Shortcut, Wait, WaitFor, MultiSelect, MultiEdit
appsyesApp
systemyesClipboard, Process, Notification
system-adminDefaults, LaunchdJob
shellShell, LaunchExecutable
filesystemFileSystem
webScrape
diagnosticsSystemInfo, Service, UnifiedLog, Network
packagesPackage
credentialsCredentials (enabled by --credentials-file)
testingAssert, CaptureEvidence
planningPlan, Apply
alwaysGuardrailStatus, 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.

sh
macos-mcp-server personas                       # first-line-support, qa-test-engineer, business-usermacos-mcp-server stdio --persona qa-test-engineermacos-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
sh
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_failEffect
allowProceeds; the failure is still recorded
warnProceeds, and the warning rides back with the result so the model sees it
holdThe call waits on an out-of-band human authoriser and fails closed
denyThis call is refused, and re-evaluated next time
killThe kill switch trips and the containment ladder runs
sh
macos-mcp-server policy validate --policy-config policy.json   # document + signal ids; exit 1macos-mcp-server policy check    --policy-config policy.json   # this device now; exit 2 if not admittedmacos-mcp-server policy explain  --policy-config policy.json --tool Shellmacos-mcp-server policy test     policy/examples/tests/*.json  # fixtures, in CImacos-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 opsinternal/macdesktop      the engine: accessibility tree, CGEvent input, ScreenCaptureKit                         screenshots, screencapture recording, keychain, launchd, log, networkinternal/macguard        pf egress enforcer, networksetup system proxy, containment actuatorinternal/clirunner       argv-only process runner with a rebuilt environmentinternal/acceptance      the tart-lab acceptance suite (MACOS_MCP_ACC=1)pkg/macos                tool definitions, toolsets, personas, resources, promptsmcp-server-core          (imported) inventory, toolkit, surface, guardrail runtime, journeys,                         schema loader, conformance fixtures and hostagentweave-harness       (imported) policy engine, audit chain, rug-pull, kill switch, egress proxypolicy/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

sh
make check              # vet, test, lintmake sign-dev           # a stable local signing identity so TCC grants survive rebuildsmake conformance        # validate the implemented product behaviormake 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.

Source: README.md at commit 8c83a77

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.1LatestOct 9, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts