macos-ui-mcp

一个 Playwright 风格的工具，让 Claude 在构建原生 macOS 应用时检查并驱动其 UI——无需屏幕录制权限。

该应用不是捕获屏幕，而是渲染自身。一个仅用于调试的微型 Swift 包（swift-harness/）通过 localhost HTTP 暴露应用的视图树和进程内 PNG 渲染器；一个 MCP 服务器（src/）将其转化为 Claude 可以调用的工具：list_windows、get_ui_tree、screenshot、click、type、wait_for、invoke_action。

有关设计原理、架构对比和项目目标，请参阅 IDEA.md。

Claude Code ──MCP(stdio)──> macos-ui-mcp server ──HTTP──> AppMCPHarness (in your app, DEBUG only)

布局

Related MCP server: Desktop Pilot MCP

使用

1. 将 harness 添加到你的 macOS 应用（仅 DEBUG 构建）

参见 swift-harness/README.md。在你的 AppDelegate 中添加一行：

#if DEBUG
AppMCP.start()   // opens http://127.0.0.1:8787
#endif

2. 构建 MCP 服务器

npm install
npm run build

3. 将其注册到 Claude Code

// .mcp.json
{
  "mcpServers": {
    "macos-ui-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/macos-ui-mcp/dist/index.js"],
      "env": { "MACOS_UI_MCP_HARNESS_URL": "http://127.0.0.1:8787" }
    }
  }
}

现在，在调试构建中运行你的应用，让 Claude 调用 get_ui_tree 或 screenshot——不会出现屏幕录制提示。

开发

npm test           # 38 unit tests, no real app needed (mock harness); e2e is skipped
npm run typecheck
npm run dev         # run the server against a live harness

npm run test:e2e    # builds showcase/, launches it, runs the real tools against the
                    # real Swift harness. Needs a logged-in macOS GUI session.

npm run test:e2e 是目标的证明：它断言 get_ui_tree 能看到控件，screenshot 返回真实的进程内 PNG，并且 click / type 能改变实时 UI——无需屏幕录制权限。

选择器语法

由 click、type、screenshot、wait_for 使用：

click / type 会拒绝不明确的选择器（多于一个匹配），并报告候选 id。

状态

• v0.1 — macOS / AppKit。已实现全部 7 个工具。38 个单元测试 + 一个 5 用例的端到端测试，通过真实的 Swift harness 驱动 showcase/ 应用。已验证：视图树、进程内 PNG 快照、点击、设置文本、操作钩子——屏幕录制已关闭。

• 尚未实现——SwiftUI 原生视图树（目前仅支持 AppKit 内省）、Windows 适配器、通过辅助功能 API 检查第三方应用。

许可证

MIT © 2026 Thang Duong

macos-ui-mcp