Macbeth

Macbeth — 适用于 macOS 的开源计算机操控工具

让你正在使用的 Agent 在 Mac 上拥有双手和双眼。

通过 MCP 或 TypeScript 查看和操控 Mac 应用，包括原生界面和 Electron 界面。

尽可能使用结构化 UI 访问。必要时使用屏幕截图和 OCR。
想象一下，Playwright 可以操控你的整台 Mac。

_{Macbeth 当前 MCP 工具集的模拟演示：系统设置、Electron 交互和屏幕截图／OCR。}

快速开始 · 示例 · 为什么选择 Macbeth？ · TypeScript · 安全 · 技能

快速开始

让 Claude Code 使用 Macbeth：

claude mcp add macbeth -- npx -y macbeth

然后让它验证连接：

使用 Macbeth 列出正在运行的应用，连接到 Finder，检查其前台窗口，并总结你能看到的前几个控件。不要执行任何其他操作。

Macbeth 附带预构建、已签名并经过公证的通用守护进程。无需 Swift 工具链，也无需手动安装服务。如果设置失败，请运行 npx macbeth doctor；它会输出一段完整独立的诊断提示词，你可以将其粘贴回 Agent。

任何能够启动 stdio 服务的 MCP 客户端都可以使用 npx -y macbeth。通用配置、更新和完整工具列表请参阅 MCP 设置。

让你的 Agent 引导安装

使用 npx -y macbeth 将 Macbeth 添加为 MCP 服务。运行 npx macbeth doctor，引导我仅授予所需权限，并通过检查 Finder 验证设置。不要执行任何无关操作。

在 Mac 上使用

在 Unity、Logic Pro 等复杂工具中操作

“在 Logic Pro 中，将项目速度设为 128 BPM 并开始播放。”

Macbeth 将结构化控件、菜单、键盘输入、屏幕截图、OCR 和特定应用的指导结合起来。Logic Pro 有一个专用技能。对于部分 Unity 界面等辅助功能树不够完善的应用，可以将结构化控件与键盘、菜单、屏幕截图和 OCR 等备用方式结合使用。

自动操作 macOS 本身

“打开系统设置，找到防火墙控件，并报告其当前状态，不要进行任何更改。”

Macbeth 可以检查具名控件及其值、选择原生菜单项，并在无法使用语义操作时通过键盘输入进行操作。

使用没有 API 的应用

“打开 HEY，找到设计团队最新的可见对话，并总结内容，不要发送或更改任何内容。”

即使服务没有提供 Agent 所需的 API，Macbeth 也可以通过暴露的 Electron 界面进行操作。HEY 使用 Macbeth 的通用 Electron 支持；结果会因应用的辅助功能树和版本而异。

看看辅助功能树遗漏了什么

“截取最前台的 Notes 窗口，并提取所有可见文本。”

ScreenCaptureKit 截图和本地 Vision OCR 可为 macOS 未能提供有用辅助功能数据的内容提供备用方案。

构建可重复使用的脚本和测试

同一引擎也提供 TypeScript API，支持延迟定位器、自动等待操作、显式状态等待、截图和应用连接。

重要

Macbeth 可以代表你在应用中执行操作。仅连接可信的 Agent，并要求在执行重要操作前获得批准。

为什么选择 Macbeth？

• 使用你自己的 Agent。 Macbeth 是控制层，不是模型或 Agent 运行时。
• 尽可能使用结构化信息。 查询角色、标签、值、启用状态、层级和稳定句柄，而不是只依赖坐标。
• 必要时使用视觉方式。 当辅助功能元数据不足时，回退到窗口捕获和 OCR。
• 了解应用。 版本化技能可保留工作流、快捷键和已知故障模式。
• 可编写脚本。 通过 MCP 交互使用相同的基础功能，也可以直接通过 TypeScript 使用。

优先使用结构化信息，而非像素

功能	常见的截图驱动 Agent	Macbeth
查找带标签的控件	视觉推断	元素公开时通过辅助功能查询
读取角色、值和状态	推断	结构化属性
等待 UI 变化	通常通过重复截图观察	显式等待和自动等待操作
处理不完整的 UI 元数据	Vision/OCR	优先使用辅助功能，截图/OCR 作为备用方案
重用应用知识	取决于提示词	随附的版本化技能

辅助功能信息本身也可能不完整或有误导性。Macbeth 采用混合式界面：macOS 提供更强的结构化基础功能时就优先使用；否则仍可使用视觉和系统级备用方案。

安全性和限制

• Macbeth 需要 macOS 14 或更高版本，以及 Node.js 20 或更高版本。
• 检查和交互 UI 需要辅助功能权限。只有在截图和窗口 OCR 时才需要屏幕录制权限。
• 应用的辅助功能质量各不相同。自定义渲染的画布、游戏和某些创意工具可能需要使用菜单、截图、OCR、键盘输入或应用专属指导。
• 应用版本之间的界面变化可能导致专门工作流失效。
• 交互光效会显示 Macbeth 的活动，但它不是审批系统，也不是完整的审计日志。
• Agent 可能会出错。对于破坏性、财务、发布或涉及隐私的操作，请进行人工审核。

Macbeth 使用本地 stdio MCP 服务和 Unix 域套接字；它不会打开 TCP 监听端口。通过 MCP 请求的截图会写入临时目录，且不会自动删除。请阅读安全模型，了解数据流、撤销权限、本地进程风险和更安全的操作实践。

TypeScript API

npm install macbeth

import { connect } from "macbeth";

const app = await connect("TextEdit");
await app.window("Untitled").textField().fill("Hello from Macbeth");
await app.pressKey("s", ["cmd"]);

有关定位器、截图、Electron 行为、生命周期和测试，请参阅使用 Macbeth 进行开发。

教 Macbeth 使用某个应用

Macbeth 技能是一个 SKILL.md 文件，可选择附带可运行脚本，用于教 Agent 掌握可靠的工作流和注意事项。不带参数调用 load_skill，即可获取Macbeth 核心指南。随附的应用技能涵盖 Calendar、Contacts、Logic Pro、Mail、Maps、Messages、Music、Notes、Reminders、Safari、System Settings 和通用 Electron 应用。

无需修改 Swift 守护进程即可添加技能。请从贡献指南开始，并附上可复现的提示词、经过测试的应用版本、预期结果以及如实说明的故障模式。

文档

指南	内容
MCP 服务	安装、冒烟测试、工具、技能和更新
CLI	每个 MCP 工具都可作为 macbeth <tool> 子命令使用
TypeScript API	客户端 API、定位器、Electron 和测试
架构	守护进程、协议、回退机制和设计说明
安全	信任边界、数据处理和权限撤销
故障排除	诊断和常见配置故障
贡献	开发工作流和应用技能

要求

• macOS 14（Sonoma）或更高版本
• Node.js 20+
• 仅当从源代码构建守护进程时需要 Swift 6.0+

许可证

MIT