m0rvayne/mcp-osascript
GitHub: m0rvayne/mcp-osascript
一个安全优先的 macOS MCP 服务器，让 AI 客户端通过 12 个类型化工具控制 Mac 的窗口、菜单、键盘和剪贴板等系统功能。
Stars: 0 | Forks: 0
# mcp-osascript
[](https://www.npmjs.com/package/mcp-osascript)
[](https://support.apple.com/macos)
[](https://nodejs.org)
[](LICENSE)
[](#testing)
**让 Claude 控制你的 Mac。** 移动窗口、点击菜单、输入文本、读取剪贴板、管理浏览器标签页 —— 包含 12 个带有类型检查、输入验证和安全防护的工具。
## 快速开始
```
{
"mcpServers": {
"osascript": {
"command": "npx",
"args": ["-y", "mcp-osascript"]
}
}
}
```
将此内容添加到你的 Claude Desktop 配置中（`设置 → 开发者 → 编辑配置`），重启 Claude，即可开始使用。
## 尝试这些提示词
安装完成后，向 Claude 提问：
| 提示词 | 执行效果 |
|--------|-------------|
| *"打开 Safari 并显示我现有的标签页"* | 启动 Safari，读取所有标签页的标题和 URL |
| *"将 Finder 窗口移至我屏幕的左半部分"* | 调整大小并重新定位窗口 |
| *"在 Keynote 中点击 文件 → 导出为 PDF"* | 导航至菜单栏并点击该项 |
| *"复制当前 Chrome 活动标签页的 URL"* | 读取浏览器标签页，找到当前活动的标签页 |
| *"在当前激活的文本框中输入 'Hello World'"* | 模拟键盘输入 |
| *"完成后显示一个通知"* | 弹出原生 macOS 横幅通知 |
| *"我现在正在使用什么应用？"* | 返回最前端应用的名称和 Bundle ID |
| *"按下 Cmd+Shift+4"* | 触发截图快捷键 |
| *"列出 VS Code 中“编辑”菜单下的所有项目"* | 内省并遍历菜单栏 |
| *"关闭终端的第二个窗口"* | 按索引指定特定的窗口进行操作 |
## 工具
12 个带有类型检查的工具，每个工具都具备输入验证、错误分类和权限感知的错误提示。
| 工具 | 功能说明 | 所需权限 |
|------|-------------|------------|
| `run_osascript` | 执行任意 AppleScript 或 JXA 脚本 | 无 |
| `get_clipboard` | 以文本形式读取剪贴板 | 无 |
| `set_clipboard` | 将文本写入剪贴板 | 无 |
| `send_notification` | 显示 macOS 通知横幅 | 无 |
| `open_url` | 在浏览器中打开 URL（仅限 http/https/mailto） | 无 |
| `open_app` | 启动应用或将其置于最前 | 无 |
| `get_frontmost_app` | 获取当前活动应用的名称 + Bundle ID | 自动化 |
| `get_browser_tabs` | 列出 Safari、Chrome 或 Arc 中的标签页 | 自动化 |
| `type_text` | 在当前激活的应用中输入文本（最多 500 个字符） | 辅助功能 |
| `press_key` | 按下带有修饰键的按键（cmd+c, return, f5） | 辅助功能 |
| `manage_windows` | 列出 / 移动 / 调整大小 / 最小化 / 全屏 / 关闭 | 辅助功能 |
| `app_menu` | 列出或点击任何应用中的菜单项 | 辅助功能 |
## 自我修正菜单
当 Claude 尝试点击一个不存在的菜单项时，服务器会自动返回该层级可用的项列表 —— 以便 Claude 可以使用正确的名称重试。没有其他 MCP 服务器能做到这一点。
```
User: "Click File → Export as PDF in Preview"
Claude: calls app_menu click ["File", "Export as PDF"]
Server: "Menu item 'Export as PDF' not found in 'File'.
Available: ['New from Clipboard', 'Open...', 'Close', 'Save',
'Duplicate', 'Rename...', 'Export...', 'Export as PDF...']"
Claude: calls app_menu click ["File", "Export as PDF..."]
Server: "Clicked: File > Export as PDF..."
```
## 为什么选择 mcp-osascript？
| | mcp-osascript | steipete (824★) | peakmojo (463★) |
|---|:---:|:---:|:---:|
| 带有验证的强类型工具 | **12** | 2（通用型） | 1（通用型） |
| URL scheme 白名单 | **http/https/mailto** | 否 | 否 |
| 环境变量隔离（子进程） | **仅限 PATH+HOME+LANG** | 完整的 process.env | 完整的 process.env |
| 进程组终止（无孤儿进程） | **SIGTERM→SIGKILL** | 否 | 否 |
| 错误信息脱敏（路径、token） | **是** | 否 | 否 |
| 原型污染防护 | **Object.create(null)** | 否 | 否 |
| 自我修正菜单点击 | **是** | 否 | 否 |
| 集成测试 | **41** | 0 | 0 |
| Stdin 管道传输（无临时文件） | **是** | 临时文件 | 临时文件 |
## 权限
工具分为三个层级运行：
- **无需权限** —— 剪贴板、通知、URL、应用。可立即使用。
- **自动化 (Automation)** —— 浏览器标签页、最前端的应用。macOS 会在每个浏览器中提示一次。
- **辅助功能 (Accessibility)** —— 键盘、窗口、菜单。在 **系统设置 → 隐私与安全性 → 辅助功能** 中授权一次即可。
当缺少权限时，服务器会准确告诉你需要做什么：
```
"Accessibility permission required. Grant access to 'osascript'
in System Settings > Privacy & Security > Accessibility."
```
## 测试
```
npm test
```
包含 41 个集成测试，覆盖了全部 12 个工具 —— 包括输入验证、安全边界（URL scheme 阻断、原型污染防护、脚本大小限制）、超时强制执行以及权限错误处理。
## 环境要求
- macOS 13+（Ventura 或更高版本）
- Node.js 18+
## 许可证
MIT
其他客户端（Cursor、VS Code、Claude Code）的配置
**Cursor / VS Code (Copilot)** ``` { "mcpServers": { "osascript": { "command": "npx", "args": ["-y", "mcp-osascript"] } } } ``` **Claude Code** ``` claude mcp add osascript -- npx -y mcp-osascript ``` **从源码构建（开发）** ``` git clone https://github.com/m0rvayne/mcp-osascript.git cd mcp-osascript && npm install # 然后使用："command": "node", "args": ["/path/to/mcp-osascript/server/index.js"] ```安全与架构
### 安全性 - `run_osascript` 会执行任意代码 —— 这是设计使然。MCP 客户端（Claude）即为信任边界。 - 脚本通过 stdin 管道传输至 `/usr/bin/osascript` —— 无临时文件，不存在 TOCTOU 竞态条件。 - 脚本大小：最大 50 KB。输出：最大 5 万字符（超出将截断）。 - 错误信息经过脱敏处理 —— 文件系统路径、token 和密码等敏感信息会被剔除。 - 子进程仅获取最少的环境变量：仅限 `PATH`、`HOME`、`LANG` —— 绝不会泄露 API 密钥或其他敏感信息。 - URL scheme 白名单 —— `file://`、`smb://`、`vnc://`、`javascript:` 均被拦截。 - Handler 分发使用 `Object.create(null)` —— 杜绝原型污染。 ### 可靠性 - 超时时执行进程组终止 —— SIGTERM → 2 秒宽限期 → SIGKILL。确保无孤儿进程残留。 - 并发信号量 —— 最多允许同时运行 5 个 osascript 进程。 - 优雅关闭 —— 执行 `server.close()` 并附带 10 秒强制退出的安全保障。 - 错误分类 —— 将 macOS 错误代码（-1728、-1743、-25211）解析为可操作的提示信息。支持英语和俄语环境。标签：AI模型上下文协议, AppleScript, Claude, CVE检测, MITM代理, 暗色界面, 桌面自动化, 自定义脚本