使用说明

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兼容客户端

快速安装

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:

{
  "mcpServers": {
    "macOS Local MCP Server": {
      "command": "/Users/YOUR_USERNAME/bin/macos-local-mcp"
    }
  }
}

替换 YOUR_USERNAME 使用您的macOS用户名（运行 whoami 检查）。

然后 重新启动克劳德桌面。服务器将出现在MCP工具部分。

连接到克劳德代码

将此添加到 ~/.claude/settings.json:

{
  "mcpServers": {
    "macOS Local MCP Server": {
      "command": "/Users/YOUR_USERNAME/bin/macos-local-mcp"
    }
  }
}

多个客户端可以同时使用服务器——每个客户端都会产生自己的进程。

macOS权限

Claude第一次使用工具时，macOS会提示您授予权限。您通常需要允许：

提醒事项 --提醒访问
日历 --日历访问
联系人 --联系人访问
邮件/消息/笔记/Safari --自动化（AppleScript）访问
访达 --聚光灯访问（通常预先授权）

授予这些 系统设置>隐私和安全.管理应用程序的访问选项卡显示已授权的权限。

配置

配置文件位于 ~/.macos-local-mcp/config.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文件、心跳）。它不与服务器进程通信。

发展

构建

swift build              # Debug build
swift build -c release   # Release build

测试

swift test               # Run all 811 tests

在本地运行

.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 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.

使用说明

macOS Local MCP Server

它的作用

建筑

工具

10个模块中的83个工具

总结

安装

需求

快速安装

连接到克劳德桌面

连接到克劳德代码

macOS权限

配置

读与写访问

确认所需工具

管理应用程序

发展

构建

测试

在本地运行

项目结构

设计原则

卸载

安全

许可证

相关 MCP

多格式文档转Markdown转换器

Markdown微信排版发布工具

谷歌表格集成工具

JavaScript逆向标准化服务

OBS控制服务器

Kali Linux MCP服务器