内容
<div align="center">
<img src="assets/banner.png" alt="mcp-osascript" width="100%">
**让 Claude 控制你的 Mac。** 移动窗口、点击菜单、输入文本、读取剪贴板、管理浏览器标签页 — 12 种输入验证和安全防护工具。
[](https://www.npmjs.com/package/mcp-osascript)
[](https://support.apple.com/macos)
[](https://nodejs.org)
[](LICENSE)
[](#testing)
</div>
---
## 快速开始
```json
{
"mcpServers": {
"osascript": {
"command": "npx",
"args": ["-y", "mcp-osascript"]
}
}
}
```
将此配置添加到你的 Claude Desktop 配置文件（`设置 → 开发者 → 编辑配置`），重启 Claude 即可开始使用。
<details>
<summary>其他客户端的配置（Cursor、VS Code、Claude Code）</summary>
**Cursor / VS Code（Copilot）**
```json
{
"mcpServers": {
"osascript": {
"command": "npx",
"args": ["-y", "mcp-osascript"]
}
}
}
```
**Claude Code**
```bash
claude mcp add osascript -- npx -y mcp-osascript
```
**从源码编译（开发）**
```bash
git clone https://github.com/m0rvayne/mcp-osascript.git
cd mcp-osascript && npm install
# 然后使用： "command": "node", "args": ["/path/to/mcp-osascript/server/index.js"]
```
</details>
## 尝试这些提示
安装完成后，询问 Claude：
| 提示 | 会发生什么 |
|--------|-------------|
| *"打开 Safari 并显示我的标签页"* | 启动 Safari，读取所有标签页标题和网址 |
| *"将 Finder 窗口移动到屏幕的左半部分"* | 调整窗口大小和位置 |
| *"点击文件 → 以 PDF 格式导出在 Keynote 中"* | 导航菜单栏并点击菜单项 |
| *"从我的活动 Chrome 标签页中复制网址"* | 读取浏览器标签页，找到活动标签页 |
| *"在活动文本字段中输入 'Hello World'"* | 模拟键盘输入 |
| *"完成后显示通知"* | 显示原生的 macOS 横幅通知 |
| *"我现在正在使用什么应用程序？"* | 返回最前面的应用程序名称和包 ID |
| *"按下 Cmd+Shift+4"* | 触发截图快捷键 |
| *"列出 VS Code 的编辑菜单中的所有项目"* | 检查菜单栏 |
| *"关闭 Terminal 的第二个窗口"* | 通过索引定位特定窗口 |
## 工具
12 种输入验证、错误分类和权限感知的工具。
| 工具 | 功能 | 权限 |
|------|-------------|------------|
| `run_osascript` | 执行任何 AppleScript 或 JXA 脚本 | 无 |
| `get_clipboard` | 读取剪贴板文本 | 无 |
| `set_clipboard` | 写入文本到剪贴板 | 无 |
| `send_notification` | 显示 macOS 通知横幅 | 无 |
| `open_url` | 在浏览器中打开网址（仅限 http/https/mailto） | 无 |
| `open_app` | 启动或将应用程序带到前台 | 无 |
| `get_frontmost_app` | 获取活动应用程序名称 + 包 ID | 自动化 |
| `get_browser_tabs` | 列出 Safari、Chrome 或 Arc 中的标签页 | 自动化 |
| `type_text` | 在活动应用程序中输入文本（最多 500 个字符） | 无障碍 |
| `press_key` | 按下带有修饰符的按键（cmd+c、return、f5） | 无障碍 |
| `manage_windows` | 列出 / 移动 / 调整大小 / 最小化 / 全屏 / 关闭 | 无障碍 |
| `app_menu` | 列出或点击任何应用程序中的菜单项 | 无障碍 |
## 自我纠正菜单
当 Claude 尝试点击不存在的菜单项时，服务器会自动返回该级别的可用菜单项列表 — 因此 Claude 可以使用正确的名称重试。其他 MCP 服务器都不具备此功能。
```
用户： "在 Preview 中点击文件 → 以 PDF 格式导出"
Claude： 调用 app_menu click ["文件", "以 PDF 格式导出"]
服务器： "菜单项 '以 PDF 格式导出' 在 '文件' 中未找到。
可用：['从剪贴板新建', '打开...', '关闭', '保存',
'复制', '重命名...', '导出...', '导出为 PDF...']"
Claude： 调用 app_menu click ["文件", "导出为 PDF..."]
服务器： "已点击：文件 > 导出为 PDF..."
```
## 为什么选择 mcp-osascript？
| | mcp-osascript | steipete (824★) | peakmojo (463★) |
|---|:---:|:---:|:---:|
| 验证工具 | **12** | 2（通用） | 1（通用） |
| 网址方案白名单 | **http/https/mailto** | 无 | 无 |
| 环境隔离（子进程） | **仅限 PATH+HOME+LANG** | 完整的 process.env | 完整的 process.env |
| 进程组终止（无孤儿进程） | **SIGTERM→SIGKILL** | 无 | 无 |
| 错误净化（路径、令牌） | **是** | 否 | 否 |
| 原型污染保护 | **Object.create(null)** | 否 | 否 |
| 自我纠正菜单点击 | **是** | 否 | 否 |
| 集成测试 | **41** | 0 | 0 |
| 标准输入管道（无临时文件） | **是** | 临时文件 | 临时文件 |
## 权限
工具分为三个层级：
- **无需权限** — 剪贴板、通知、网址、应用程序。即时生效。
- **自动化** — 浏览器标签页、最前面的应用程序。macOS 每个浏览器提示一次。
- **无障碍** — 键盘、窗口、菜单。在 **系统设置 → 隐私和安全 → 无障碍** 中授予一次。
当权限缺失时，服务器会准确告诉您需要执行的操作：
```
"需要无障碍权限。 在系统设置 > 隐私和安全 > 无障碍中授予 'osascript' 的访问权限。"
```
## 测试
```bash
npm test
```
41 个集成测试涵盖所有 12 种工具 — 输入验证、安全边界（网址方案阻止、原型污染、脚本大小限制）、超时强制执行和权限错误处理。
<details>
<summary>安全性和架构</summary>
### 安全
- `run_osascript` 执行任意代码 — 这是设计使然。MCP 客户端（Claude）是信任边界。
- 通过标准输入将脚本传输到 `/usr/bin/osascript` — 无临时文件，无 TOCTOU 竞争条件。
- 脚本大小：最大 50 KB。输出：最大 50K 字符（截断）。
- 错误消息净化 — 清除文件系统路径、令牌和密码。
- 子进程获取最小环境：仅限 `PATH`、`HOME`、`LANG` — 不会泄露 API 密钥或机密。
- 网址方案白名单 — 阻止 `file://`、`smb://`、`vnc://`、`javascript:`。
- 处理程序调度使用 `Object.create(null)` — 无原型污染。
### 可靠性
- 超时时杀死进程组 — SIGTERM → 2 秒宽限期 → SIGKILL。无孤儿进程。
- 并发信号量 — 最多 5 个同时 osascript 进程。
- 正常关闭 — `server.close()`，并带有 10 秒强制退出安全网。
- 错误分类 — 将 macOS 错误代码（-1728、-1743、-25211）解析为可操作的错误信息。支持英语和俄语区域。
</details>
## 要求
- macOS 13+（Ventura 或更高版本）
- Node.js 18+
## 许可证
MIT
