MCP server for controlling macOS via AppleScript/osascript - Full system automation
npm install control-your-mac
基于 AppleScript/osascript 实现的 MCP (Model Context Protocol) 服务器,让 Claude 等 AI 助手能够完整控制和自动化 macOS 系统。
此 MCP 服务器提供 33 个强大的工具:
osascript | 执行任意 AppleScript 代码,提供完整的 macOS 自动化能力 |get_system_info | 获取系统信息(电脑、用户、磁盘、内存、CPU、网络、电池等) |system_settings | 打开系统设置或切换 Wi-Fi、蓝牙、AirDrop |power_control | 系统电源控制(睡眠、重启、关机、登出) |control_application | 控制应用(打开、退出、激活、隐藏、显示、重启、列出运行中的应用) |control_window | 窗口管理(列出、最小化、最大化、关闭、移动、调整大小、全屏) |control_volume | 音量控制(设置、获取、静音、取消静音) |control_display | 显示设置(深色模式开关、获取外观设置) |screen_control | 屏幕控制(睡眠、唤醒、锁屏、启动屏保) |screenshot | 截图(全屏、选区、窗口) |speech | 文字转语音(朗读、获取可用声音、停止) |keyboard | 模拟键盘输入(打字、按键、快捷键) |mouse | 鼠标控制(点击、双击、右键、移动) |show_dialog | 显示对话框(提示、文件选择、列表选择等) |show_notification | 显示系统通知 |clipboard | 剪贴板操作(获取、设置、清空) |file_operation | 文件操作(打开、在 Finder 中显示、移至废纸篓、获取信息) |finder | Finder 高级操作(管理文件、视图切换、隐藏文件、快速预览、磁盘管理) |browser | 浏览器控制(Safari/Chrome:打开URL、管理标签页、导航、搜索、执行JS) |open_url | 快速打开URL(使用默认或指定浏览器) |music | Apple Music 控制(播放、暂停、跳过、播放列表、随机、重复、喜欢/不喜欢) |focus | 勿扰模式/专注模式控制 |calendar | 日历控制(列出日历、今日事件、创建事件、搜索事件) |reminders | 提醒事项控制(列出、创建、完成、删除提醒) |notes | 备忘录控制(列出、创建、搜索、读取、追加、删除笔记) |mail | 邮件控制(检查邮件、列出未读、撰写、发送、搜索) |contacts | 联系人控制(搜索、查看、创建、删除联系人) |spotlight | Spotlight 搜索(搜索文件、应用、最近文件) |shell | 执行 Shell 命令(带安全检查) |terminal | Terminal/iTerm 控制(打开窗口、运行命令、导航) |monitor | 系统监控(CPU、内存、磁盘、进程、网络连接) |wifi | Wi-Fi 控制(连接/断开、列出网络、获取IP/DNS) |messages | iMessage/短信控制(发送消息、列出聊天) |- Node.js 18 或更高版本
- macOS 系统(Sonoma 14.0+ 推荐)
- Claude Desktop 或其他支持 MCP 的客户端
``bash克隆仓库
git clone https://github.com/yourusername/control-your-mac.git
cd control-your-mac
⚙️ 配置 Claude Desktop
编辑 Claude Desktop 配置文件:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json`json
{
"mcpServers": {
"control-your-mac": {
"command": "node",
"args": [
"/path/to/control-your-mac/dist/index.js"
]
}
}
}
`> 📝 将
/path/to/control-your-mac 替换为你的实际安装路径🔐 权限设置
首次使用时,macOS 会要求授予以下权限:
1. 系统设置 > 隐私与安全性 > 辅助功能
- 添加 Claude Desktop(或 Terminal/iTerm)到允许列表
2. 系统设置 > 隐私与安全性 > 自动化
- 允许 Claude Desktop 控制其他应用程序
3. 部分功能需要的额外权限:
- 截图:屏幕录制权限
- 鼠标控制:辅助功能权限
📖 使用示例
配置完成后,你可以在 Claude 中使用自然语言:
$3
`
帮我打开 Safari 浏览器
关闭 Terminal
列出所有正在运行的应用
`$3
`
把音量调到 50%
开启深色模式
获取系统信息
`$3
`
把 Safari 窗口移到左边
最大化当前窗口
列出所有打开的窗口
`$3
`
按下 Command+C 复制
把"Hello World"放到剪贴板
模拟输入文字 "测试内容"
`$3
`
在 Finder 中显示我的下载文件夹
截取全屏截图
`$3
`
显示一个通知,标题是"任务完成",内容是"构建已完成"
弹出一个提示框让用户输入名字
`$3
`
帮我执行 AppleScript:获取 Finder 中当前选中的文件路径
`🛠️ 开发
$3
`
control-your-mac/
├── src/
│ ├── index.ts # MCP 服务器主入口
│ ├── types.ts # Zod schemas 和类型定义
│ ├── utils.ts # AppleScript 执行工具
│ ├── errors.ts # 自定义错误类
│ ├── logger.ts # 日志系统
│ └── tools/ # 各功能模块(29 个工具文件)
│ ├── application.ts
│ ├── browser.ts
│ ├── calendar.ts
│ ├── ... # 更多工具模块
│ └── index.ts
├── tests/ # 单元测试
│ └── tools.test.ts
├── dist/ # 编译输出
├── vitest.config.ts # 测试配置
├── eslint.config.js # ESLint 配置
├── package.json
├── tsconfig.json
├── CHANGELOG.md # 变更日志
└── README.md
`$3
`bash
构建
npm run build # 构建项目
npm run watch # 监听模式构建
npm run dev # 构建并运行
npm run start # 运行服务器
npm run clean # 清理构建
npm run rebuild # 重新构建测试
npm run test # 运行单元测试
npm run test:watch # 监听模式测试
npm run test:coverage # 测试覆盖率代码质量
npm run lint # ESLint 检查
npm run lint:fix # 自动修复 lint 问题
npm run format # Prettier 格式化
npm run typecheck # TypeScript 类型检查调试
npm run inspect # 使用 MCP Inspector 调试
`$3
使用 MCP Inspector 进行调试:
`bash
npm run inspect
`或直接运行:
`bash
npx @modelcontextprotocol/inspector node dist/index.js
`🔧 故障排除
$3
如果遇到权限错误:
- 确保应用在「辅助功能」和「自动化」权限列表中
- 尝试重启 Claude Desktop
- 在终端运行
tccutil reset AppleEvents 重置自动化权限$3
- 检查 AppleScript 语法是否正确
- 确认目标应用程序已安装且名称正确
- 某些系统操作可能需要管理员权限
$3
鼠标控制依赖 Python3 和 Quartz(macOS 自带):
`bash
python3 -c "import Quartz; print('Quartz OK')"
`⚠️ 安全注意事项
- 此工具提供完整的 macOS 系统控制能力
- 仅在受信任的环境中使用
- 不要与不受信任的第三方共享访问权限
-
power_control 工具可以关机/重启系统,请谨慎使用📚 参考资源
- Model Context Protocol 文档
- AppleScript 语言指南
- MCP SDK 文档
📄 许可证
MIT License - 详见 LICENSE
🤝 贡献
欢迎提交 Issue 和 Pull Request!
1. Fork 本仓库
2. 创建功能分支 (
git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature`)