mac-use-mcp

mac-use-mcp

警告

此工具可完全控制鼠标、键盘和屏幕。 请在沙盒环境中使用，以保护隐私，并避免 Agent 意外造成数据丢失。您需要对通过此工具执行的任何操作负责。

通过 MCP 实现零原生依赖的 macOS 桌面自动化。

让 AI Agent 在 macOS 上拥有眼睛和双手——点击、输入、截屏并检查任何应用程序。

使用场景

• 自动化 UI 测试 — 点击按钮，使用 get_ui_elements 验证元素状态，通过 screenshot 验证屏幕内容
• 桌面工作流自动化 — 使用 open_application 启动应用，使用 type_text 填写表单，通过 click_menu 浏览菜单
• 基于屏幕截图的监控 — 定期使用 screenshot 捕获屏幕区域，用于视觉差异比较或告警
• 无障碍检查 — 查询 UI 元素树，使用 get_ui_elements 进行 QA 和合规检查
• AI Agent 使用计算机 — 通过 screenshot、click、type_text 等工具，让大模型在 macOS 上拥有眼睛和双手

为什么选择 mac-use-mcp？

• 开箱即用 — 运行 npx mac-use-mcp 并授予两项 macOS 权限即可。无需 node-gyp、Xcode 工具或构建步骤。
• 18 种工具，一个服务 — 支持屏幕截图、点击、按键、窗口管理、无障碍检查和剪贴板。
• 适用于 Intel 和 Apple Silicon 的 macOS 13+ — 无原生扩展，无架构兼容问题。

安装

要求： macOS 13+ 和 Node.js 22+。服务使用 stdio 传输方式进行通信。

此软件包仅适用于 macOS。在其他操作系统上安装时会拒绝安装。

无需构建步骤。无需原生依赖。直接运行：

npx mac-use-mcp

首次运行时，npx 会提示安装软件包。使用 npx -y mac-use-mcp 可跳过确认。

提示

模型选择很重要。 桌面自动化涉及屏幕截图与操作的循环，累计起来会消耗大量令牌。建议使用速度快、推理能力强、视觉能力好且工具调用可靠的模型：

模型	提供方
Gemini 3 Flash	Google
Claude Sonnet 4.6	Anthropic
GPT-5 mini	OpenAI
MiniMax-M2.5	MiniMax
Kimi K2.5	Moonshot AI
Qwen3.5	Alibaba
GLM-4.7	Zhipu AI

权限设置

mac-use-mcp 需要两项 macOS 权限才能运行。授予一次即可。

辅助功能

鼠标和键盘控制所需权限。

1. 打开 系统设置 > 隐私与安全性 > 辅助功能
2. 点击 + 按钮
3. 添加您的 MCP 客户端应用（例如 Claude Desktop 或终端模拟器）
4. 确保开关已启用

屏幕录制

截屏所需权限。

1. 打开 系统设置 > 隐私与安全性 > 屏幕录制
2. 点击 + 按钮
3. 添加您的 MCP 客户端应用
4. 确保开关已启用
5. 如果系统提示，请重新启动应用

验证权限

授予这两项权限并配置 MCP 客户端后（参见下一节），使用 check_permissions 工具确认一切正常：

> check_permissions
✓ Accessibility: granted
✓ Screen Recording: granted

MCP 客户端配置

claude mcp add mac-use-mcp -- npx mac-use-mcp

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

[mcp_servers.mac-use]
command = "npx"
args = ["-y", "mac-use-mcp"]

codex mcp add mac-use -- npx -y mac-use-mcp

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

{
  "servers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

{
  "mcpServers": {
    "mac-use-mcp": {
      "command": "npx",
      "args": ["mac-use-mcp"]
    }
  }
}

工具

这个 Node.js MCP 服务向任何兼容 MCP 的客户端提供 18 个用于鼠标、键盘和屏幕控制的工具。

屏幕

输入

窗口与应用

应用名称支持模糊匹配——"chrome" 会匹配到 "Google Chrome"，"code" 会匹配到 "Code"，等等。

辅助功能

剪贴板

实用工具

示例

使用 mac-use-mcp 工具的常见工作流模式：

截取特定窗口

1. focus_window({ app: "Safari" })
2. screenshot({ mode: "window", window_title: "Safari" })

点击对话框中的按钮

1. get_ui_elements({ app: "Finder", role: "AXButton" })
   → finds "OK" button at position (500, 300)
2. click({ x: 500, y: 300 })

自动执行菜单操作

1. open_application({ name: "TextEdit" })
2. click_menu({ app: "TextEdit", path: "Format > Make Plain Text" })

在应用之间复制文本

1. focus_window({ app: "Safari" })
2. press_key({ key: "cmd+a" })       # select all
3. press_key({ key: "cmd+c" })       # copy
4. focus_window({ app: "Notes" })
5. press_key({ key: "cmd+v" })       # paste

工作原理

• Swift 二进制文件处理鼠标输入（CGEvent）、屏幕捕获（CGWindowListCreateImage）、窗口枚举（CGWindowListCopyWindowInfo）和 UI 元素查询（Accessibility API）
• AppleScript处理键盘输入（System Events key code）、窗口聚焦和菜单点击
• Node.js MCP 服务通过 stdio 协调所有操作，将 MCP 工具调用转换为系统操作
• 不使用原生 Node.js 插件——Swift 二进制文件已预编译，并随 npm 包一起提供
• 串行执行队列可防止系统操作之间发生竞态条件

已知限制

• Sequoia 上的屏幕录制提示：macOS 15 每月会显示系统提示，要求重新确认屏幕录制权限。这是操作系统级行为，无法禁用。
• 安全输入字段：密码字段和其他安全文本输入框会阻止模拟键盘事件。这是 macOS 的安全功能。
• macOS 26+ 上的键盘输入：CGEvent 键盘合成会被静默阻止。键盘输入会使用 AppleScript（System Events key code）作为变通方案，在某些边缘情况下行为可能有所不同。
• 系统对话框：由于 macOS 的安全限制，某些系统级对话框（例如 FileVault 解锁窗口、登录窗口）无法通过编程方式交互。
• 无头环境 / CI：需要图形会话。不支持无头 macOS 环境（例如标准 GitHub Actions 运行器）。

故障排除

相关项目

• Playwright MCP — 通过辅助功能树实现浏览器自动化。可与 mac-use-mcp 配合，用于仅涉及 Web 的任务。
• Peekaboo — 使用 ScreenCaptureKit 实现 macOS 屏幕自动化。需要 macOS 15+ 和 Swift 构建环境。
• awesome-mcp-servers — 精选的生态系统 MCP 服务列表。

贡献

开发环境设置和指南请参阅 CONTRIBUTING.md。

更新日志

安全

如需报告漏洞，请参阅 SECURITY.md。

支持

• 发现了 Bug？提交问题
• 有功能创意？提交问题
• 喜欢这个项目？给它点个星，帮助更多人发现 mac-use-mcp。

许可证

MIT © 2026 antbotlab

macOS 是 Apple Inc. 在美国及其他国家和地区注册的商标。