macOS MCP Server

macos-mcp-server

一个 Model Context Protocol 服务，可将 AI Agent 接入 macOS 桌面：辅助功能树、模拟鼠标和键盘输入、屏幕截图、窗口和应用控制、Shell、 偏好设置、launchd、进程、文件系统和网页抓取。无需计算机视觉模型：Agent 通过辅助功能树感知 UI， 就像辅助技术那样。

它是 windows-mcp-server 的 macOS 对应版本： 两者拥有相同的 35 个工具、工具集、角色、策略文档和工作流程。它们与普通自动化桥接工具的不同之处在于，每项 Agent 操作都 以实时设备安全状态为准入条件，Agent 的网络出口受到限制， 且两者都会记录在 Agent 无法关闭的防篡改审计链中。

• 设备策略引擎：每次工具调用、资源读取和提示词获取都会在运行前，根据实时设备信号（MDM 注册、Platform SSO、启动 安全性、FileVault、SIP、密封系统卷）进行评估，并由策略拒绝、警告或限制。规则可按工具、工具集或注释匹配，因此屏幕截图不会像 Shell 命令那样受到相同限制。 → 策略配置
• 网络出口允许列表：回环代理仅允许访问你声明的域名，还可选择配合 pf 规则，防止控制台用户或整台机器绕过代理。→ 网络出口
• 防篡改透明机制：哈希链审计日志（使用密钥并锚定到统一日志）、心跳、检测策略突变、整场会话录制、证据包，以及带外分级终止开关。这些机制均无法由 Agent 禁用。→ 安全架构

若干工具（Shell、LaunchExecutable、Defaults、LaunchdJob、FileSystem、 Process、App）拥有完整的用户级系统访问权限，且不受沙盒限制。 这是设计使然。在虚拟机中运行不受信任的工作负载，参见 VM 隔离；有关哪些情况属于或不属于漏洞的范围，请阅读 SECURITY.md。

需要在 Apple silicon 上运行 macOS 27 或更高版本。 Apple 不支持 Intel Mac 运行 macOS 27。

---

快速开始

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

对于 Claude Desktop，请从最新 GitHub 版本下载 .mcpb，并通过 Settings > Extensions > Advanced settings > Install Extension 进行安装。它包含已签名的服务二进制文件，并会在首次启动时申请所需的 macOS 授权。

任何其他本地 MCP 客户端都可以使用 stdio 子命令启动二进制文件：

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

→ 开始使用 介绍 Claude Code、Cursor、 Codex CLI 和 Claude Desktop，以及在将其用于你重视的机器之前需要做些什么。→ 权限 说明隐私授权，以及签名身份为何重要。

不确定这是否适合你？如果需要在设备群中批准它，请阅读 决定是否部署。如果你有具体任务要完成，请查看以下操作指南： UI 回归测试套件或 一线支持队列。

---

功能

	功能说明	指南
桌面自动化	35 个工具，涵盖 13 个工具集：辅助功能树感知、AX 操作、模拟输入、屏幕截图、应用、窗口、Shell、偏好设置、文件系统、进程、launchd、统一日志、网络、软件包、抓取、规划与执行	工具集与角色
角色	预设配置，可选择工具集 并 注入工作流指导	工具集与角色
凭据	Agent 无需获知机密即可登录应用和网站：Credentials 工具没有读取模式，注入操作要求使用安全文本字段，并且每种退出路径都会移除钥匙串项目	凭据
会话录制	设置 transparency.recording_dir 后，整个会话会录制到一个带时间线标记的 .mov 文件中	会话录制
操作流程	以声明式定义的 UI 操作流程，可离线验证、通过规划器运行，并从人工操作会话中录制	操作流程
紧急停止开关	带外分级遏制：隔离（pf）、终止进程、锁定、关机，并在此之前先完成录制并撤销凭据	安全架构
MCP 一致性	每个 PR 都会依据最新发布的规范检查已实现的协议行为	MCP 合规性

---

工具

工具集	默认启用	工具
screen	是	Snapshot、Screenshot、DisplayInventory、Recording
interaction	是	Click、Type、Invoke、GetText、Scroll、Move、Shortcut、Wait、WaitFor、MultiSelect、MultiEdit
apps	是	App
system	是	Clipboard、Process、Notification
system-admin		Defaults、LaunchdJob
shell		Shell、LaunchExecutable
filesystem		FileSystem
web		Scrape
diagnostics		SystemInfo、Service、UnifiedLog、Network
packages		Package
credentials		Credentials（通过 --credentials-file 启用）
testing		Assert、CaptureEvidence
planning		Plan、Apply
always		GuardrailStatus、Kill

有四个名称与 Windows 服务不同，因为它们指代不同的子系统：Defaults（Registry）、Shell（PowerShell）、LaunchdJob（ScheduledTask）和 UnifiedLog（EventLog）。其他所有内容，包括操作流程词汇，都完全相同。

资源：macos://desktop/snapshot、macos://desktop/displays、macos://session/recording、macos://system/info。提示词：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

按设计无法自动化的内容

登录窗口、锁定屏幕、Touch ID 和密码面板、TCC 同意对话框，以及安全文本字段的内容。这些是系统自身的信任边界；服务不会尝试越过它们。

---

安全

📐 安全架构 · 📄 策略配置 · 🔎 安全评估

策略引擎位于 MCP 客户端与工具之间：

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

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

未指定 --policy-config 时，将应用内置默认策略：引擎会运行，评估每个已声明的信号并记录每项判定，但不会拒绝任何操作。在编写策略之前，采用该引擎不会破坏正常运行的部署。

on_fail	效果
allow	继续执行；仍会记录失败
warn	继续执行，并将警告随结果一并返回，以便模型看到
hold	调用会等待带外人工授权；若未获授权则拒绝
deny	拒绝此次调用，并在下次重新评估
kill	触发终止开关并启动遏制阶梯

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

policy/examples/ 中附带了七个起始策略：audit.json（建议先采用，不拒绝任何操作）、secure.json、enterprise.json、locked-down.json、egress.json、dual-control.json 和 evidence-export.json。

信任模型

本地设备信号是可审计的纵深防御措施，并非坚固的边界：root 可以伪造这些信号，而且隐私授权基于签名身份，而非二进制文件的哈希。遏制层会提高会话内攻击的代价并记录相关情况；请将其与 MDM、Gatekeeper 和公证、Platform SSO 和 Conditional Access 以及 FileVault 配合使用。在信任设备安全态势之前，值得了解 macOS 的两点特性：pf 按套接字所有者过滤，因此“限定范围”出口层约束的是控制台用户，而非指定应用；此外，安全态势信号采用 Windows 命名，但文档说明了 macOS 上的对应含义。这两点都在评估报告中详细说明。

---

MCP 合规性

每个 PR 都会针对最新发布的 MCP 规范版本运行必需的 MCP 规范检查。该检查会捕获产品实际公布的功能范围和原始线路响应，根据已发布的架构检查定义和安全的方法调用，并在需要评估更新的规范版本时失败。检查覆盖此服务实现的功能，不会为未实现的可选功能计算百分比。参见 MCP 规范检查。

---

架构

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

所有辅助功能、事件和 AppKit 工作均通过 Desktop.Do 在进程主线程上运行；工具处理程序则通过接收中间件从请求上下文获取依赖项。

---

开发

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

发布由 release-please 切分，并通过 release.yml 构建：一个 arm64 二进制文件，经 Developer ID 签名和公证后，打包为 tarball 和 Claude Desktop .mcpb。发布还附带 CycloneDX SBOM 和无密钥 cosign 签名；经过测试的 cask 会发布到 deploymenttheory/homebrew-tap。在资源通过验证前，发布版本会保持为草稿。安装和升级方法请参阅入门指南。

---

文档

docs/：设置与配置指南、安全架构与评估、旅程词汇表及合规性报告。

许可证

MIT，详见 LICENSE。