Macos MCP (macos-mcp)

macos mcp

一个全面的模型上下文协议（MCP）服务器，提供通过AppleScript控制macOS系统功能的工具。通过简单的界面控制Mac的应用程序、系统设置等。

特性

音频工具

• get_volume_settings -获取所有音量设置（输出、输入、警报、静音状态）
• get_volume -获取当前输出音量（0-100）
• set_volume -设置输出音量级别
• is_muted -检查音频是否已静音
• mute -将音频输出静音
• unmute -取消音频输出静音
• toggle_mute -切换静音状态
• beep -播放系统蜂鸣声

日历工具

• calendar_list_calendars -列出所有日历
• calendar_list_events -使用日期筛选列出日历事件
• calendar_create_event -创建包含位置、注释等的新日历事件
• calendar_delete_event -按标题删除日历事件

Chrome工具

• chrome_get_all_tabs -列出所有Chrome窗口中的所有选项卡
• chrome_get_active_tab -获取当前活动选项卡
• chrome_open_url -在新选项卡中打开URL
• chrome_close_tab -关闭特定选项卡
• chrome_reload_tab -重新加载特定选项卡
• chrome_execute_javascript -在选项卡中执行JavaScript
• chrome_get_windows -列出所有Chrome窗口
• chrome_scroll -按像素滚动页面或滚动到顶部/底部

联系人工具

• contacts_list_people -列出所有联系人
• contacts_create_contact -使用姓名、电子邮件、电话、组织创建新联系人
• contacts_delete_contact -删除联系人
• contacts_list_groups -列出所有联系人组
• contacts_search -按姓名、电子邮件或组织搜索联系人
• contacts_update -更新现有联系信息
• contacts_add_to_group -将联系人添加到组

查找工具

• finder_open_path -在Finder中打开文件或文件夹
• finder_new_window -打开一个新的Finder窗口
• finder_get_selection -获取当前选定的项目
• finder_get_current_path -获取当前Finder目录
• finder_set_view -更改Finder视图模式
• finder_search -在Finder中搜索文件
• finder_move_to_trash -将文件移至回收站
• finder_empty_trash -清空垃圾桶
• finder_create_folder -创建新文件夹

邮件工具

• get_mail_accounts -列出已配置的Apple Mail帐户
• get_mails -从收件箱获取电子邮件
• compose_mail -用收件人、主题、正文撰写新电子邮件
• search_mails -按主题、发件人或内容搜索电子邮件
• check_mail -检查新邮件
• get_unread_count -获取每个邮箱的未读计数
• get_total_unread_count -获取未读总计数

通知工具

• send_notification -显示带有标题、消息、字幕和声音的macOS原生通知
• send_notification_with_actions -显示带有自定义操作按钮（接受/拒绝等）的交互式对话框
• send_alert_with_actions -使用自定义操作按钮显示突出的警报（用于重要确认）
• send_notification_with_text_input -使用自定义按钮提示用户输入文本（支持密码模式）

笔记工具

• notes_list_folders -列出所有Notes文件夹
• notes_list_notes -列出文件夹中的笔记
• notes_create_note -创建新笔记（支持HTML）
• notes_delete_note -删除注释
• notes_update -更新笔记内容
• notes_search -按标题或内容搜索笔记
• notes_create_folder -创建新文件夹
• notes_move -将笔记移动到其他文件夹
• notes_get -获取特定注释的详细信息
• notes_delete_folder -删除文件夹
• notes_get_folder_info -获取文件夹信息
• notes_search_in_folder -在特定文件夹内搜索
• notes_search_by_title -仅按标题搜索

提醒工具

• reminders_get_lists -获取所有提醒列表
• reminders_get_reminders -从列表中获取提醒
• reminders_create_reminder -创建具有截止日期和优先级的新提醒
• reminders_complete_reminder -将提醒标记为已完成
• reminders_delete_reminder -删除提醒
• reminders_update -更新提醒详细信息
• reminders_create_list -创建新的提醒列表
• reminders_delete_list -删除提醒列表
• reminders_search -按标题或正文搜索提醒

Safari工具

• safari_get_all_tabs -列出所有Safari窗口中的所有选项卡
• safari_get_active_tab -获取当前活动选项卡
• safari_open_url -在新选项卡中打开URL
• safari_close_tab -关闭特定选项卡
• safari_reload_tab -重新加载特定选项卡
• safari_execute_javascript -在选项卡中执行JavaScript
• safari_get_windows -列出所有Safari窗口
• safari_navigate -导航到当前选项卡中的URL
• safari_search_web -执行网络搜索
• safari_go_back -返回历史记录
• safari_go_forward -在历史中向前导航

终端工具

• terminal_get_windows -列出所有终端窗口
• terminal_get_tabs -在窗口中列出选项卡
• terminal_execute_command -在选项卡中执行命令
• terminal_new_window -创建新的终端窗口
• terminal_new_tab -创建新选项卡
• terminal_close_tab -关闭特定选项卡
• terminal_get_current_directory -获取当前工作目录
• terminal_get_contents -获取终端输出内容
• terminal_clear -清除终端屏幕

安装

npm install -g macos-mcp
# or
bunx macos-mcp

用法

克劳德桌面版

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "macos": {
      "command": "bunx",
      "args": ["macos-mcp"]
    }
  }
}

或者，如果全局安装：

{
  "mcpServers": {
    "macos": {
      "command": "macos-mcp"
    }
  }
}

克劳德代码

添加到您的Claude Code MCP设置中(~/.claude/settings.json):

  claude mcp add-json macos '{"type":"stdio","command":"bunx","args":["macos-mcp"]}' --scope user

或

{
  "mcpServers": {
    "macos": {
      "command": "bunx",
      "args": ["macos-mcp"]
    }
  }
}

直接运行

# With bun
bun run macos-mcp

# Or after global install
macos-mcp

交互式CLI

该项目还包括一个用于测试和手动控制的交互式CLI：

# Run the CLI
bun run cli

# Or with npm
npm run cli

看 cli/README.md 有关交互式CLI的更多详细信息。

MCP检验员测试

npx @modelcontextprotocol/inspector bunx macos-mcp

权限

此MCP服务器使用AppleScript来控制macOS功能。您可能需要授予权限：

1. 无障碍：系统设置>隐私和安全>辅助功能
2. 自动化：系统设置>隐私和安全>自动化
3. 应用程序权限：当首次访问应用程序（邮件、日历、联系人、笔记、提醒）时，macOS将提示您获得权限

项目结构

cli/                # Interactive CLI interface
├── audio.ts        # Audio controls
├── calendar.ts     # Calendar management
├── chrome.ts       # Chrome browser control
├── contacts.ts     # Contacts management
├── finder.ts       # Finder operations
├── mail.ts         # Mail operations
├── notes.ts        # Notes management
├── notification.ts # Notification controls
├── reminders.ts    # Reminders management
├── safari.ts       # Safari browser control
├── terminal.ts     # Terminal control
└── index.ts        # CLI entry point

mcp/                # MCP server
├── index.ts        # Tool definitions and handlers
├── macos-mcp.ts    # MCP server entry point
├── tools/          # Tool definitions
└── handlers/       # Tool handlers

src/                # Core functionality
├── audio/          # Audio control functions
├── calendar/       # Calendar functions
├── chrome/         # Chrome automation
├── contacts/       # Contacts management
├── finder/         # Finder operations
├── mail/           # Apple Mail functions
├── notes/          # Notes functions
├── notification/   # Notification and dialog functions
├── reminders/      # Reminders functions
├── safari/         # Safari automation
└── terminal/       # Terminal control

发展

本地开发

# Clone the repo
git clone https://github.com/kartikk-k/macos-mcp.git
cd macos-mcp

# Install dependencies
bun install

# Run the MCP server
bun run start

# Run the interactive CLI
bun run cli

# Test with inspector
bun run inspector

添加新工具

1. 将您的函数添加到中的相应模块 src/
2. 从模块导出 index.ts
3. 将工具定义添加到 mcp/tools/{module}.ts
4. 在中添加处理程序 mcp/handlers/{module}.ts
5. （可选）在中添加CLI界面 cli/{module}.ts

看 CLAUDE.md 详细的开发指南。

许可证

麻省理工学院