macOS Local MCP Server
Bridge Claude Desktop to every native app on your Mac.
Reminders · Calendar · Mail · Messages · Notes · Contacts · Safari · Finder · Shortcuts · Cross-App
本地人 模型上下文协议 用Swift编写的服务器,让Claude可以直接访问 10个macOS模块 通过 83名工具操作员 --再加上一个用于管理一切的原生SwiftUI管理应用程序。
零网络,零依赖。零遥测。 一切都在你的Mac上本地运行。
它的作用
macOS本地MCP服务器将Claude变成了macOS的原生电动工具。适用于Claude Desktop、Claude Code或任何MCP客户端。请克劳德:
- “这周我的日程表上有什么?” --通过EventKit读取日历
- “提醒我明天早上9点给牙医打电话” --创建提醒
- “在我的电子邮件中搜索Acme Corp的发票” --搜索邮件
- “给Sarah发消息:我要迟到10分钟了” --发送iMessage(带确认)
- “在我的桌面上查找所有PDF” --搜索聚光灯
- “运行我的‘晨间例行’快捷方式” --执行快捷方式(带确认)
- “为我下午2点的会议做好准备” --聚合日历、联系人和电子邮件上下文
所有83个工具都通过stdio上的MCP协议工作——没有HTTP服务器,没有云中继,没有API密钥。
建筑```
┌──────────────────┐ ┌──────────────────────┐
│ Claude Desktop │──┐ │ │
└──────────────────┘ │ stdio (JSON-RPC 2.0) │ macos-local-mcp server │
┌──────────────────┐ ├──────────────────────────────────► │ │
│ Claude Code │──┘ (each client spawns its own) │ │
└──────────────────┘ └──────────┬───────────┘
│
┌──────────────────────────────────────┼──────────────────────────────┐
│ │ │
┌─────────▼──────────┐ ┌─────────────▼───────────┐ ┌───────────▼──────────┐
│ EventKit │ │ NSAppleScript / JXA │ │ Shell Commands │
│ Reminders │ │ Mail │ │ Finder / Spotlight │
│ Calendar │ │ Messages │ │ Shortcuts │
│ Contacts │ │ Notes │ └──────────────────────┘
└────────────────────┘ │ Safari │
└─────────────────────────┘
┌────────────────────────────┐
│ Cross-App (aggregator) │ ← Combines data from multiple
│ meeting_context │ providers (no own bridge)
│ contact_360 │
└────────────────────────────┘
┌──────────────────────────┐
│ macOS Local MCP Admin │ ← SwiftUI app in /Applications
│ (reads ~/.macos-local-mcp/) │ Monitors server, manages config,
│ │ controls read/write access per module
└──────────────────────────┘
**两个构建目标:**
|二进制|描述|
|--------|-------------|
| `macos-local-mcp` |无头MCP服务器。通过stdin/stdout进行通信。每个MCP客户端都会生成自己的进程。 |
| `macOS Local MCP Server.app` |原生SwiftUI管理应用程序。监控服务器状态、活动日志、权限和模块配置。 |
______________________________________________________________________
## 工具
### 10个模块中的83个工具
每个工具被分类为 **阅读** 或 **写**,让您对克劳德可以访问的内容进行精细控制。
Reminders — 8 tools
|工具|访问|描述|
|------|--------|-------------|
| `list_reminder_lists` |阅读|列出所有提醒列表(类别)|
| `list_reminders` |阅读|使用过滤器列出提醒(列表、日期范围、状态、优先级)|
| `search_reminders` |阅读|通过文本查询搜索提醒|
| `create_reminder` |写|创建一个提醒,包括截止日期、优先级、列表分配|
| `update_reminder` |写入|更新提醒的属性|
| `complete_reminder` |写|将提醒标记为已完成|
| `move_reminder` |写|将提醒移动到其他列表|
| `bulk_move_reminders` |写入|一次在列表之间移动多个提醒|
Calendar — 11 tools
|工具|访问|描述|
|------|--------|-------------|
| `list_calendars` |阅读|列出所有可用日历|
| `list_events` |读取|列出日期范围内的事件|
| `search_events` |读取|按文本查询搜索事件|
| `check_availability` |阅读|检查某个时间范围的可用性|
| `find_conflicts` |读取|查找日期范围内的重叠/冲突事件|
| `find_gaps` |阅读|查找活动之间的空闲时段|
| `get_calendar_stats` |读取|获取日期范围内的事件计数和时间统计信息|
| `create_event` |编写|创建日历事件|
| `update_event` |写入|更新现有事件|
| `delete_event` |写入|删除事件 *(需要确认)* |
| `bulk_decline_events` |写入|同时拒绝多个事件 *(需要确认)* |
Contacts — 13 tools
|工具|访问|描述|
|------|--------|-------------|
| `search_contacts` |阅读|按姓名、电子邮件、电话或公司搜索|
| `get_contact` |阅读|获取完整详细信息,包括创建日期/修改日期|
| `list_contact_groups` |阅读|列出所有联系人组|
| `get_contacts_in_group` |阅读|获取组中的所有联系人|
| `find_incomplete_contacts` |阅读|查找缺少关键字段(电子邮件、电话、公司)的联系人|
| `list_all_contacts` |读取|列出所有具有限制/偏移分页的联系人|
| `create_contact` |写|创建新联系人|
| `update_contact` |写入|更新联系人信息|
| `delete_contact` |写|删除联系人 *(需要确认)* |
| `bulk_update_contacts` |写入|一次更新多个联系人的字段|
| `merge_contacts` |写入|将两个联系人合并为一个 *(需要确认)* |
| `create_contact_group` |写|创建新的联系人组|
| `add_contact_to_group` |写|将联系人添加到组中|
Mail — 12 tools
|工具|访问|描述|
|------|--------|-------------|
| `list_mailboxes` |读取|列出所有邮件帐户和邮箱|
| `list_recent_mail` |阅读|使用过滤器列出最近的电子邮件|
| `search_mail` |阅读|按发件人、主题、正文、日期、附件搜索|
| `read_mail` |阅读|阅读邮件的全部内容|
| `find_unanswered_mail` |阅读|查找您尚未回复的已收到电子邮件|
| `find_threads_awaiting_reply` |阅读|查找您正在等待响应的线程|
| `list_senders_by_frequency` |阅读|按电子邮件频率列出发件人|
| `create_draft` |编写|创建新的电子邮件草稿|
| `send_draft` |写|发送草稿 *(需要确认)* |
| `move_message` |写|将邮件移动到另一个邮箱|
| `flag_message` |写入|标记或标记为已读/未读|
| `bulk_archive_messages` |写入|一次存档多封邮件 *(需要确认)* |
Messages — 4 tools
|工具|访问|描述|
|------|--------|-------------|
| `list_conversations` |阅读|列出最近的iMessage/SMS对话|
| `read_conversation` |阅读|阅读对话中的消息|
| `search_messages` |阅读|搜索邮件历史记录|
| `send_message` |写|发送iMessage或短信 *(需要确认)* |
Notes — 9 tools
|工具|访问|描述|
|------|--------|-------------|
| `list_note_folders` |阅读|列出所有笔记文件夹/帐户|
| `list_notes` |阅读|列出带有过滤器、排序和限制/偏移分页的注释|
| `read_note` |阅读|阅读笔记的全部内容|
| `search_notes` |阅读|按文本查询搜索笔记|
| `find_stale_notes` |阅读|查找N天内未修改的笔记,并分页|
| `create_note` |写|创建新笔记|
| `update_note` |写|更新笔记内容|
| `delete_note` |写|删除注释 *(需要确认)* |
| `append_to_note` |写入|将文本附加到现有注释中|
Safari — 15 tools
|工具|访问|描述|
|------|--------|-------------|
| `list_open_tabs` |阅读|列出窗口中所有打开的选项卡|
| `list_reading_list` |阅读|列出阅读列表项|
| `search_bookmarks` |阅读|搜索书签|
| `search_history` |阅读|搜索浏览历史记录|
| `list_bookmark_folders` |阅读|列出所有书签文件夹|
| `find_duplicate_tabs` |阅读|查找打开到同一URL的选项卡|
| `get_tab_content` |读取|从选项卡获取页面内容|
| `add_to_reading_list` |写入|将URL添加到阅读列表|
| `add_bookmark` |写入|将书签添加到文件夹|
| `delete_bookmark` |写入|删除书签 *(需要确认)* |
| `create_bookmark_folder` |写入|创建新书签文件夹|
| `close_tab` |写入|关闭选项卡 *(需要确认)* |
| `close_tabs_matching` |写入|关闭与URL模式匹配的所有选项卡 *(需要确认)* |
| `new_tab` |写入|在新选项卡中打开URL|
| `reload_tab` |写入|重新加载选项卡|
Finder — 6 tools
|工具|访问|描述|
|------|--------|-------------|
| `spotlight_search` |读取|使用Spotlight元数据搜索文件|
| `spotlight_search_content` |阅读|通过Spotlight搜索文件内容|
| `get_file_metadata` |读取|获取文件大小、日期、类型、标签|
| `list_finder_tags` |阅读|列出所有正在使用的Finder标签|
| `get_tagged_files` |读取|获取带有特定标签的文件|
| `set_finder_tags` |在文件或文件夹上写入|设置Finder标签|
Shortcuts — 3 tools
|工具|访问|描述|
|------|--------|-------------|
| `list_shortcuts` |阅读|列出所有可用快捷方式|
| `get_shortcut_details` |阅读|获取快捷方式的详细信息|
| `run_shortcut` |按名称编写|运行快捷方式 *(需要确认)* |
Cross-App — 2 tools
|工具|访问|描述|
|------|--------|-------------|
| `meeting_context` |阅读|获取包含与会者联系信息和最近电子邮件的即将召开的会议|
| `contact_360` |阅读|联系人的全方位视图:详细信息、电子邮件、消息、事件|
### 总结
||读|写|总计|
|---|:---:|:---:|:---:|
| **提醒事项** | 3 | 5 | 8 |
| **日历** | 7 | 4 | 11 |
| **联系人** | 6 | 7 | 13 |
| **邮件** | 7 | 5 | 12 |
| **消息** | 3 | 1 | 4 |
| **备注** | 5 | 4 | 9 |
| **游猎** | 7 | 8 | 15 |
| **访达** | 5 | 1 | 6 |
| **捷径** | 2 | 1 | 3 |
| **跨应用程序** | 2 | 0 | 2 |
| **总计** | **47** | **36** | **83** |
______________________________________________________________________
## 安装
### 需求
- **macOS 13.0** (文图拉)或更晚
- **Swift 5.9+** (Xcode 15+附带)
- **克劳德桌面** (下载)或 **克劳德代码** 或任何MCP兼容客户端
### 快速安装```bash
git clone https://github.com/amargautam/macos-local-mcp.git
cd macos-local-mcp
bash install.sh
这将:
- 在发布模式下构建两个目标
- 将服务器二进制文件安装到
~/bin/macos-local-mcp - 在以下位置创建配置
~/.macos-local-mcp/config.json - 将管理应用程序安装到
/Applications/macOS Local MCP Server.app
连接到克劳德桌面
将此添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:```json
{
"mcpServers": {
"macOS Local MCP Server": {
"command": "/Users/YOUR_USERNAME/bin/macos-local-mcp"
}
}
}
替换 `YOUR_USERNAME` 使用您的macOS用户名(运行 `whoami` 检查)。
然后 **重新启动克劳德桌面**。服务器将出现在MCP工具部分。
### 连接到克劳德代码
将此添加到 `~/.claude/settings.json`:```json
{
"mcpServers": {
"macOS Local MCP Server": {
"command": "/Users/YOUR_USERNAME/bin/macos-local-mcp"
}
}
}
多个客户端可以同时使用服务器——每个客户端都会产生自己的进程。
macOS权限
Claude第一次使用工具时,macOS会提示您授予权限。您通常需要允许:
- 提醒事项 --提醒访问
- 日历 --日历访问
- 联系人 --联系人访问
- 邮件/消息/笔记/Safari --自动化(AppleScript)访问
- 访达 --聚光灯访问(通常预先授权)
授予这些 系统设置>隐私和安全.管理应用程序的 访问 选项卡显示已授权的权限。
配置
配置文件位于 ~/.macos-local-mcp/config.json:```json
{
"logLevel": "normal",
"logMaxSizeMB": 10,
"enabledModules": {
"reminders": {"read": true, "write": false},
"calendar": {"read": true, "write": false},
"contacts": {"read": true, "write": false},
"mail": {"read": true, "write": false},
"messages": {"read": true, "write": false},
"notes": {"read": true, "write": false},
"safari": {"read": true, "write": false},
"finder": {"read": true, "write": false},
"shortcuts": {"read": true, "write": false},
"crossapp": {"read": true, "write": false}
}
}
> **默认值:只读。** 所有模块在出厂时都禁用了写入权限。根据需要启用按模块写入。
### 读与写访问
每个模块都可以独立配置 **阅读** 和 **写** 访问:
- **阅读** 工具: `list_*`, `search_*`, `get_*`, `read_*`, `check_*` --安全、非破坏性查询
- **写** 工具: `create_*`, `update_*`, `delete_*`, `send_*`, `run_*` --修改状态的操作
将模块设置为 `{"read": true, "write": false}` 为了 **只读** 模式。这让Claude可以搜索和查看您的数据,而无需修改任何内容。
### 确认所需工具
13种高影响力工具需要明确 `confirmation: true` 执行前的参数:
|工具|为什么|
|------|-----|
| `send_message` |向真人发送iMessage/SMS|
| `send_draft` |发送电子邮件|
| `delete_event` |永久删除日历事件|
| `delete_note` |永久删除笔记|
| `delete_contact` |永久删除联系人|
| `merge_contacts` |合并两个联系人(删除源)|
| `close_tab` |关闭Safari选项卡|
| `run_shortcut` |执行任意快捷方式自动化|
| `complete_reminder` |将提醒标记为已完成|
| `bulk_decline_events` |同时拒绝多个日历事件|
| `bulk_archive_messages` |一次归档多封电子邮件|
| `delete_bookmark` |删除Safari书签|
| `close_tabs_matching` |关闭与URL模式匹配的所有选项卡|
______________________________________________________________________
## 管理应用程序
打开 **macOS本地MCP服务器** 从 `/Applications` 或聚光灯。
管理应用程序提供五种视图:
|查看|目的|
|------|---------|
| **概述** |服务器状态(运行/停止)、PID、正常运行时间、最近活动、快速统计数据|
| **活动** |完整的工具调用日志——按成功/错误/确认过滤,可搜索,可排序|
| **访问** |每个模块的macOS权限状态——一目了然地查看授权/拒绝的内容|
| **模块** |切换每个模块的读/写访问权限——更改会立即保存到配置中|
| **设置** |日志级别、最大日志大小、每个工具的确认要求|
管理应用程序直接读取 `~/.macos-local-mcp/` (配置、活动日志、PID文件、心跳)。它不与服务器进程通信。
______________________________________________________________________
## 发展
### 构建```bash
swift build # Debug build
swift build -c release # Release build
测试```bash
swift test # Run all 811 tests
### 在本地运行```bash
.build/debug/macos-local-mcp # Start the server (reads from stdin, writes to stdout)
项目结构```
Sources/
├── MacOSLocalMCP/ # MCP server
│ ├── main.swift # Entry point — wires all 10 modules + cross-app
│ ├── MCPServer.swift # JSON-RPC server, request routing
│ ├── ConfigManager.swift # Config parsing, file watching
│ ├── ActivityLogger.swift # Structured tool call logging
│ ├── HeartbeatManager.swift # Heartbeat file for admin app
│ ├── Models/
│ │ ├── MCPTypes.swift # MCP protocol types (JSON-RPC, tools)
│ │ └── ToolDefinitions.swift # All 83 tool schemas + access levels
│ ├── Protocols/ # 9 bridge protocols (DI interfaces)
│ ├── Bridges/ # 10 concrete bridge implementations
│ └── Tools/ # 10 tool modules + cross-app + handler utilities
│
├── MacOSLocalMCPAdmin/ # SwiftUI admin app
│ ├── MacOSLocalMCPAdminApp.swift # App entry point
│ ├── AppState.swift # Shared observable state
│ ├── Models/ # Config, activity, status models
│ ├── Services/ # File-based services (monitor, config, feed)
│ └── Views/ # 5 detail views + sidebar
│
Tests/
├── MacOSLocalMCPTests/ # Server tests (763 tests)
└── MacOSLocalMCPAdminTests/ # Admin app tests (48 tests)
### 设计原则
- **基于协议的DI** --每个网桥都有一个协议;工具依赖于协议,而不是具体的类型
- **测试驱动开发** --首先编写所有811个测试,然后执行
- **零网络** --没有 `URLSession` 代码库中的任何位置
- **零依赖** --只有Swift stdlib和苹果系统框架
- **不得强行打开包装** --没有 `!` 在生产代码中
- **确认执行** --破坏性工具强制执行 `confirmation: true` 在工具层和服务器层
______________________________________________________________________
## 卸载```bash
bash uninstall.sh
这将删除二进制文件和可选的配置目录。还删除 /Applications/macOS Local MCP Server.app 如果已安装。
安全
- 仅限本地 --服务器仅通过stdio进行通信。没有打开端口,没有HTTP服务器,没有云中继。每个MCP客户端都会生成自己的隔离子流程。
- 无遥测 --没有任何东西被发送到任何地方。所有数据都保留在Mac上。
- 无依赖关系 --没有第三方Swift包。攻击面是Swift stdlib和Apple框架。
- 默认拒绝 --所有模块都是只读的。每个模块都必须明确启用写访问。
- 确认门 --13种高冲击工具需要明确
confirmation: true在执行之前。 - 预防注射 --AppleScript输入经过净化(CR/LF剥离),SQL查询使用引号加倍,Spotlight查询经过净化,shell命令使用
Process使用单独的参数(无插值)。 - 路径遍历保护 --文件操作阻止对系统目录的访问(
/System,/Library,/usr,/bin,/sbin,/etc,/var). - 限制文件权限 --所有运行时文件(配置、日志、心跳、PID)都是通过以下方式创建的
0o700目录和0o600文件夹。 - macOS权限 --服务器在您的用户帐户下运行,并尊重每个应用程序的macOS权限提示。
许可证
麻省理工学院
Built with Claude Code by a multi-agent team of specialized engineers.
