MCP AppleScript
一个本地MCP服务器，在macOS上向MCP客户端公开受控的AppleScript自动化工具。
\[！小心\] 该软件可以读取、创建、修改和删除您的个人数据 跨笔记、日历、提醒、邮件、联系人、消息、照片、音乐、Finder和Safari。 通过运行此服务器，您授予AI模型代表您与macOS应用程序交互的能力。尽管存在多个安全层（操作模式、每个应用程序的分配、破坏性动作确认）， 没有一种自动防护措施是万无一失的。意外的提示、配置错误的策略或模型幻觉可能会导致 数据丢失、私人信息泄露或意外行为 例如发送消息或电子邮件。 您全权负责： - 回顾和理解 配置 和 政策模型 启用任何应用程序之前 - 开始于readonly模式，只有当你了解后果时才会升级 - 将启用的应用程序数量保持在您实际需要的最低限度 - 从不跑步full无人值守模式 本项目提供 按原样，不提供任何保证。参见 许可证.
概述
MCP AppleScript在 模型上下文协议 通过AppleScript实现macOS自动化。它由两个部分组成：
- MCP服务器（Types/Node.js）：处理MCP协议、工具模式、配置、验证、日志记录和策略执行
- Swift执行器：通过执行AppleScript命令
NSAppleScript并返回结构化JSON结果
工具
所有10个苹果应用程序都可以通过通用 app.* 工具与a app 参数：
| 工具 | 模式 | 描述 |
|---|---|---|
applescript.ping | 只读 | 运行状况检查--返回服务器版本和支持的应用程序 |
applescript.get_mode | 只读 | 获取当前操作模式和启用的工具 |
applescript.set_mode | 只读 | 更改操作模式（只读/创建/完整） |
app.list_containers | 只读 | 列出容器（文件夹、日历、邮箱、播放列表等） |
app.list | readonly | 用分页列出容器中的项目 |
app.get | 只读 | 按ID获取单个项目 |
app.search | 只读 | 搜索/筛选项目 |
app.create | create | 创建新项目 |
app.action | 创建 | 特定于应用程序的操作（发送、播放、完成、do_javascript等） |
applescript.run_template | create | 按ID执行已注册的模板（策略门控） |
app.update | 完整 | 更新项目（需要确认） |
app.delete | full | 删除项目（需要确认） |
applescript.run_script | full | 执行原始AppleScript（需要确认） |
支持的应用程序
笔记、日历、提醒、邮件、通讯录、消息、照片、音乐、查找器、Safari浏览器
操作模式
服务器启动于 只读 默认模式。使用 applescript.set_mode 要动态更改模式：
| 模式 | 描述 | 可用工具 |
|---|---|---|
| 只读 | 不创建、编辑或删除 | ping、get_mode、set_mode、app.list/get/search/list_containers |
| 创造 | 允许只读+创建 | +app.create、app.action、run_template |
| 满的 | 所有可能具有破坏性的操作 | +app.update、app.delete、run_script（需要确认） |
当模式更改时，会通过以下方式通知客户端 notifications/tools/list_changed 并且只会看到当前模式下可用的工具。
破坏性行动确认
在 满的 破坏性工具模式(app.update, app.delete, run_script)需要用户确认：
- 如果MCP客户端支持 引出，显示确认对话框
- 否则，a 确认令牌 返回--在第二次呼叫中将其传递回以进行确认
需求
- macOS 12.0或更高版本
- Node.js 20+（仅用于从源代码构建）
- Swift 5.9+（仅适用于从源代码构建）
- pnpm 8+（仅适用于从源构建）
安装
选项1：下载预构建的二进制文件（.dmg）
下载最新 .dmg 从 :
- 打开
.dmg并复制mcp-applescript到/usr/local/bin/:
sudo cp /Volumes/MCP-AppleScript\ */mcp-applescript /usr/local/bin/- 创建配置文件：
mkdir -p ~/.config/applescript-mcp
cat > ~/.config/applescript-mcp/config.json << 'EOF'
{
"defaultMode": "readonly",
"apps": {
"com.apple.Notes": { "enabled": true },
"com.apple.iCal": { "enabled": true },
"com.apple.reminders": { "enabled": true },
"com.apple.mail": { "enabled": true },
"com.apple.Contacts": { "enabled": true }
}
}
EOF- 添加到您的MCP客户端配置中（请参阅下面的Claude Desktop）
预构建的二进制文件是一个自包含的可执行文件，内嵌了Node.js和Swift执行器，不需要运行时依赖。
选项2：从源代码构建
git clone https://github.com/frouaix/MCPAppleScript.git
cd MCPAppleScript
./install.sh安装脚本将：
- 安装Node.js依赖项
- 构建TypeScript MCP服务器
- 构建并安装Swift执行器
/usr/local/bin/ - 在以下位置创建默认配置
~/.config/applescript-mcp/config.json
Claude桌面集成
增添 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"applescript": {
"command": "/usr/local/bin/mcp-applescript"
}
}
}如果从源代码构建，请使用dev路径：
{
"mcpServers": {
"applescript": {
"command": "node",
"args": ["/path/to/MCPAppleScript/packages/mcp-server/dist/index.js"]
}
}
}配置
配置存在于 ~/.config/applescript-mcp/config.json （通过以下方式覆盖 APPLESCRIPT_MCP_CONFIG env 是：
{
"executorPath": "/usr/local/bin/applescript-executor",
"defaultTimeoutMs": 12000,
"defaultMode": "readonly",
"modes": {
"readonly": ["applescript.ping", "applescript.get_mode", "applescript.set_mode", "app.list_containers", "app.list", "app.get", "app.search"],
"create": ["app.create", "app.action", "applescript.run_template"],
"full": ["app.update", "app.delete", "applescript.run_script"]
},
"apps": {
"com.apple.Notes": { "enabled": true },
"com.apple.iCal": { "enabled": true },
"com.apple.reminders": { "enabled": true },
"com.apple.mail": { "enabled": true },
"com.apple.Contacts": { "enabled": true },
"com.apple.MobileSMS": { "enabled": true },
"com.apple.Photos": { "enabled": true },
"com.apple.Music": { "enabled": true },
"com.apple.finder": { "enabled": true },
"com.apple.Safari": { "enabled": true }
},
"runScript": {
"enabled": false,
"allowedBundleIds": []
},
"logging": {
"level": "info",
"redact": ["email", "content", "body"]
}
}模式
这 modes 部分控制在每个操作模式级别可用的工具。模式是累积的-- create 包括所有 readonly 工具， full 包括所有 create 工具。您可以对此进行自定义，以将工具提升到较低的模式或将其限制到较高的模式。
策略模型
- 按应用程序分配列表：每个应用程序都必须明确配置和启用
- 按工具权限：控制哪些工具可以针对哪些应用程序
- 每模式工具门控：每个工具都需要一个最低模式级别（可通过以下方式配置
modes) run_script默认情况下禁用：原始AppleScript执行需要显式选择加入- 强制超时：所有操作都有时间限制
自动化权限（TCC）
首次使用时，macOS将提示输入自动化权限：
- 打开 系统设置 → 隐私和安全 → 自动化
- 查找您的终端或执行器二进制文件
- 为要自动化的应用程序启用权限（笔记、日历、提醒、邮件、联系人等）
如果你看到 AUTOMATION_DENIED 错误，请检查这些权限。
建筑
MCP Client (Claude, etc.)
↕ stdio (JSON-RPC)
TypeScript MCP Server
↕ JSON over stdin/stdout
Swift Executor (applescript-executor)
↕ Apple Events
macOS Apps (Notes, Calendar, Reminders, Mail, Contacts, Messages, Photos, Music, Finder, Safari)节点进程是唯一面向MCP的组件。Swift是每次工具调用在本地调用的助手。看 docs/ARCHITECTURE.md 了解详情。
发展
# Install dependencies
pnpm install
# Build everything
pnpm build
# Run unit tests (150 tests)
pnpm test:unit
# Run integration tests (4 tests, requires macOS)
pnpm test:integration
# Build Swift executor
cd packages/executor-swift && swift build
# Run the server in development mode
cd packages/mcp-server && pnpm dev构建独立二进制文件
# Build self-contained binary (Node.js SEA + embedded Swift executor)
pnpm build:sea
# Package as .dmg
pnpm build:dmg输出： dist/mcp-applescript （约107MB，约40MB，以.dmg计）
安全
- 三种操作模式 （只读→ 创造→ 已满），默认为安全
- 破坏性行动确认 通过MCP启发或确认令牌
- 基于模板的执行 防止任意脚本注入
- 每个应用程序、每个工具权限模型 与明确的排外主义者
- 输入验证 在所有工具参数上使用Zod模式
- 敏感数据编辑 在日志中（可配置）
- 超时执行 关于所有执行器操作
- 稳定的错误代码 适用于所有故障模式
项目结构
MCPAppleScript/
packages/
mcp-server/ # TypeScript MCP server
src/
index.ts # Stdio entrypoint
server.ts # MCP server + tool registration
sea.ts # SEA binary support (executor extraction)
adapters/ # ResourceAdapter pattern: per-app adapters (10 apps)
config/ # Configuration loading + Zod schemas
mode/ # Operation mode manager + confirmation
policy/ # Allowlist/denylist enforcement
exec/ # Executor spawning + IPC
util/ # Errors, logging, JSON utils
executor-swift/ # Swift executor CLI
Sources/Executor/
main.swift # JSON dispatcher
AppleScriptRunner.swift # Template dispatch to per-app modules
{App}Templates.swift # Per-app AppleScript templates (10 files)
AppTargeting.swift # Bundle ID handling
Errors.swift # Error code mapping
JsonIO.swift # Stdin/stdout JSON I/O
scripts/
build-sea.sh # Build self-contained binary (Node.js SEA)
build-dmg.sh # Package binary as .dmg
docs/ # Architecture documentation
install.sh # One-step installer (build from source)许可证
麻省理工学院——见 许可证
作者
弗朗索瓦 Rouaix