Macos Local MCP Server

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
└──────────────────────────┘

两个构建目标：

______________________________________________________________________

工具

10个模块中的83个工具

每个工具被分类为 阅读 或 写，让您对克劳德可以访问的内容进行精细控制。

Reminders — 8 tools

Calendar — 11 tools

Contacts — 13 tools

Mail — 12 tools

Messages — 4 tools

Notes — 9 tools

Safari — 15 tools

Finder — 6 tools

Shortcuts — 3 tools

Cross-App — 2 tools

总结

______________________________________________________________________

安装

需求

• 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

这将：

1. 在发布模式下构建两个目标
2. 将服务器二进制文件安装到 ~/bin/macos-local-mcp
3. 在以下位置创建配置 ~/.macos-local-mcp/config.json
4. 将管理应用程序安装到 /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 执行前的参数：

______________________________________________________________________

管理应用程序

打开 macOS本地MCP服务器 从 /Applications 或聚光灯。

管理应用程序提供五种视图：

管理应用程序直接读取 ~/.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.