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 的客户端

安装步骤

# 克隆仓库
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

{
  "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 中使用自然语言：

应用控制

帮我打开 Safari 浏览器
关闭 Terminal
列出所有正在运行的应用

系统设置

把音量调到 50%
开启深色模式
获取系统信息

窗口管理

把 Safari 窗口移到左边
最大化当前窗口
列出所有打开的窗口

键盘和剪贴板

按下 Command+C 复制
把"Hello World"放到剪贴板
模拟输入文字 "测试内容"

文件操作

在 Finder 中显示我的下载文件夹
截取全屏截图

通知和对话框

显示一个通知，标题是"任务完成"，内容是"构建已完成"
弹出一个提示框让用户输入名字

高级自动化

帮我执行 AppleScript：获取 Finder 中当前选中的文件路径

🛠️ 开发

项目结构

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

开发命令

# 构建
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 调试

调试

使用 MCP Inspector 进行调试：

npm run inspect

或直接运行：

npx @modelcontextprotocol/inspector node dist/index.js

🔧 故障排除

权限问题

如果遇到权限错误：

• 确保应用在「辅助功能」和「自动化」权限列表中
• 尝试重启 Claude Desktop
• 在终端运行 tccutil reset AppleEvents 重置自动化权限

脚本执行失败

• 检查 AppleScript 语法是否正确
• 确认目标应用程序已安装且名称正确
• 某些系统操作可能需要管理员权限

鼠标控制不工作

鼠标控制依赖 Python3 和 Quartz（macOS 自带）：

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