Control Your Mac

基于 AppleScript/osascript 实现的 MCP (Model Context Protocol) 服务器，让 Claude 等 AI 助手能够完整控制和自动化 macOS 系统。

✨ 功能特性

此 MCP 服务器提供 33 个强大的工具：

$3

| 工具 | 功能 |
|------|------|
| osascript | 执行任意 AppleScript 代码，提供完整的 macOS 自动化能力 |
| get_system_info | 获取系统信息（电脑、用户、磁盘、内存、CPU、网络、电池等） |
| system_settings | 打开系统设置或切换 Wi-Fi、蓝牙、AirDrop |
| power_control | 系统电源控制（睡眠、重启、关机、登出） |

$3

| 工具 | 功能 |
|------|------|
| control_application | 控制应用（打开、退出、激活、隐藏、显示、重启、列出运行中的应用） |
| control_window | 窗口管理（列出、最小化、最大化、关闭、移动、调整大小、全屏） |

$3

| 工具 | 功能 |
|------|------|
| control_volume | 音量控制（设置、获取、静音、取消静音） |
| control_display | 显示设置（深色模式开关、获取外观设置） |
| screen_control | 屏幕控制（睡眠、唤醒、锁屏、启动屏保） |
| screenshot | 截图（全屏、选区、窗口） |
| speech | 文字转语音（朗读、获取可用声音、停止） |

$3

| 工具 | 功能 |
|------|------|
| keyboard | 模拟键盘输入（打字、按键、快捷键） |
| mouse | 鼠标控制（点击、双击、右键、移动） |
| show_dialog | 显示对话框（提示、文件选择、列表选择等） |
| show_notification | 显示系统通知 |

$3

| 工具 | 功能 |
|------|------|
| clipboard | 剪贴板操作（获取、设置、清空） |
| file_operation | 文件操作（打开、在 Finder 中显示、移至废纸篓、获取信息） |
| finder | Finder 高级操作（管理文件、视图切换、隐藏文件、快速预览、磁盘管理） |

$3

| 工具 | 功能 |
|------|------|
| browser | 浏览器控制（Safari/Chrome：打开URL、管理标签页、导航、搜索、执行JS） |
| open_url | 快速打开URL（使用默认或指定浏览器） |

$3

| 工具 | 功能 |
|------|------|
| music | Apple Music 控制（播放、暂停、跳过、播放列表、随机、重复、喜欢/不喜欢） |
| focus | 勿扰模式/专注模式控制 |

$3

| 工具 | 功能 |
|------|------|
| calendar | 日历控制（列出日历、今日事件、创建事件、搜索事件） |
| reminders | 提醒事项控制（列出、创建、完成、删除提醒） |
| notes | 备忘录控制（列出、创建、搜索、读取、追加、删除笔记） |
| mail | 邮件控制（检查邮件、列出未读、撰写、发送、搜索） |
| contacts | 联系人控制（搜索、查看、创建、删除联系人） |

$3

| 工具 | 功能 |
|------|------|
| spotlight | Spotlight 搜索（搜索文件、应用、最近文件） |
| shell | 执行 Shell 命令（带安全检查） |
| terminal | Terminal/iTerm 控制（打开窗口、运行命令、导航） |

$3

| 工具 | 功能 |
|------|------|
| monitor | 系统监控（CPU、内存、磁盘、进程、网络连接） |
| wifi | Wi-Fi 控制（连接/断开、列出网络、获取IP/DNS） |

$3

| 工具 | 功能 |
|------|------|
| messages | iMessage/短信控制（发送消息、列出聊天） |

📦 安装

$3

- Node.js 18 或更高版本
- macOS 系统（Sonoma 14.0+ 推荐）
- Claude Desktop 或其他支持 MCP 的客户端

$3

``bash


克隆仓库

git clone https://github.com/yourusername/control-your-mac.git
cd control-your-mac

安装依赖

npm install

构建项目

npm run build
`

⚙️ 配置 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`)
5. 打开 Pull Request