macos-mcp

从 AI 代理或 shell 驱动 macOS 上的 Reminders、Calendar、Notes、Mail、Messages 和 Contacts。

Apple 为这些应用提供了三种自动化接口，但每一种都有缺陷。EventKit 无法访问 Notes、Mail、Messages 或 Contacts。在 Sonoma 及更高版本上，JXA 读取 Messages 返回空结果。JXA 读取真实收件箱中的 Mail 会在 60 秒超时。本项目使用每个应用可用的桥接方式，并在 DECISION.md 中记录了原因。

需要 Mac。 这些桥接依赖 EventKit、Apple Events 以及对本地 Apple 数据库的 SQLite 读取。没有 Linux、Windows、iOS、Android 或浏览器版本。

三种使用方式

作为 MCP 服务器。 本地 stdio 传输，可与同一台 Mac 上的任何支持 MCP 的客户端配合使用（Claude Code、Claude Desktop、Cursor、Zed、Continue、ChatGPT 桌面版）。共八个工具，见工具列表。

作为代理技能（skill）。 相同的桥接以 shell 命令方式调用，无需在上下文中加载工具模式。MCP 服务器会在会话开始时将全部八个工具定义展示给模型，无论会话是否涉及 Mac 应用；技能则只有一行描述，直到触发条件满足才展开。技能见 skills/macos/，如何选择见 docs/mcp-vs-skill.md。

作为 CLI。 EventKitCLI 是一个独立的 Swift 二进制，在 stdout 上输出 JSON。技能中的 JXA 和 SQLite 配方可在任何有 shell 的环境中运行。

Related MCP server: Apple MCP

快速开始

安装为 Claude Code 插件

/plugin marketplace add krmj22/macos-mcp
/plugin install macos-mcp@krmj22-plugins

在 Claude Code 中运行以下命令。该插件通过 npx -y mcp-macos 配置 MCP 服务器，因此无需单独的安装步骤。

从 npm 安装

npm install -g mcp-macos
# or use npx via your client's MCP config (no global install needed)

或通过 MCPB 安装（Claude Desktop）

从最新 GitHub 发布页下载 .mcpb 包并拖到 Claude Desktop 上。该包包含预构建的通用 Swift 二进制（arm64 + x86_64），因此无需 Xcode Command Line Tools。

或从源码构建

git clone https://github.com/krmj22/macos-mcp.git
cd macos-mcp
pnpm install
pnpm build

验证安装

macos-mcp --check   # or: node dist/index.js --check

检查 macOS 版本、Node.js、EventKit 二进制、完全磁盘访问权限（Full Disk Access）和 JXA 自动化权限。

或将其用作技能而非服务器

将技能复制到代理的技能目录中。无需 MCP 服务器，也无需在上下文中加载工具模式。

git clone https://github.com/krmj22/macos-mcp.git
cp -R macos-mcp/skills/macos ~/.claude/skills/macos

该技能直接调用 EventKitCLI、osascript 和 sqlite3，因此需要将 Swift 二进制加入 PATH：

cd "$(mktemp -d)" && npm i mcp-macos --no-save \
  && mkdir -p ~/.local/lib/mcp-macos/bin \
  && cp node_modules/mcp-macos/bin/EventKitCLI ~/.local/lib/mcp-macos/bin/EventKitCLI \
  && ln -sf ~/.local/lib/mcp-macos/bin/EventKitCLI ~/.local/bin/EventKitCLI

两种方式所需的权限相同。见权限。

工具

下划线（reminders_tasks）和点号（reminders.tasks）两种写法都可用。

设计说明

• 读取用 SQLite，写入用 JXA。 JXA 读取 Mail 无法扩展，在真实收件箱上会达到 60 秒超时；JXA 读取 Messages 在 macOS Sonoma 及更高版本上完全失效。本项目直接读取 chat.db 和 Mail 的 Envelope Index，包括用于 [Gmail]/All Mail 账户的 Gmail labels 连接表。写入仍通过 JXA，因为 Apple Events 是唯一能触发写入的 API。见 ADR-001。

• 按应用混合后端。 每个应用使用可用的桥接：Reminders 和 Calendar 通过 EventKit 使用 Swift CLI，Notes、Contacts、Mail 写入和 Messages 发送使用 JXA，Mail 和 Messages 读取使用 SQLite。架构图 展示了扇出结构。

• 跨工具联系人增强。 共享层将原始电话号码和电子邮件地址解析为联系人姓名，覆盖 Messages、Mail 和 Calendar。通过 SQLite AddressBook 存储进行批量缓存，1100 条记录耗时低于 50ms；定向查询通过 JXA whose() 实现。见 ADR-002。

• 预检检查。 macos-mcp --check 在运行前验证 macOS 版本、Node.js、EventKit 二进制、完全磁盘访问权限和 JXA 权限，并对任何失败项提供指向相关系统设置（System Settings）面板的深层链接。

安装

前置条件

• Node.js 20+

• macOS

• Xcode Command Line Tools（Swift 编译）

客户端配置

所有客户端的 JSON 配置相同，只是位置不同。

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

权限

macOS 会在首次使用时提示授权。出现提示时点击允许。

Messages 和 Mail 直接读取 SQLite 数据库，因此你的终端应用（Terminal、iTerm2 等）需要完全磁盘访问权限（Full Disk Access）。

运行 macos-mcp --check 进行验证。如有任何失败，见故障排除。

故障排除

快速修复命令

# Open specific settings panes
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Reminders"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Calendars"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

完全磁盘访问权限（Messages 和 Mail）

Messages 和 Mail 读取 SQLite 数据库（~/Library/Messages/chat.db 和 ~/Library/Mail/V10/MailData/Envelope Index）。这需要终端应用拥有完全磁盘访问权限。

# Find your real node binary (version managers use shims)
node -e "console.log(process.execPath)"

# Reveal it in Finder for drag-and-drop into FDA settings
open -R "$(node -e "console.log(process.execPath)")"

# Open Full Disk Access settings
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

版本管理器用户（Volta、nvm、fnm）：node 命令是一个垫片（shim）。系统设置需要真实的二进制：

系统设置可能不会显示隐藏目录中的二进制。使用上面的 open -R 在 Finder 中显示它，然后拖入 FDA 列表。

JXA 自动化（Notes、Mail、Contacts）

首次使用时，macOS 会提示自动化访问权限。通过系统设置 > 隐私与安全性 > 自动化授予。

验证权限：

osascript -l JavaScript -e 'Application("Contacts").people().length'
osascript -l JavaScript -e 'Application("Calendar").calendars().length'
osascript -l JavaScript -e 'Application("Reminders").defaultList().name()'
osascript -l JavaScript -e 'Application("Mail").inbox().messages().length'
osascript -l JavaScript -e 'Application("Notes").notes().length'

每条命令都应返回一个值。如果挂起，说明权限对话框正在尝试（但未能）弹出。

Gmail 标签 / 收件箱消息缺失

Gmail 将所有消息存储在 [Gmail]/All Mail 中，并使用标签表示文件夹成员关系。服务器同时检查直接邮箱和标签连接表。如果 Gmail 收件箱消息缺失，请确认 Mail 应用已完全同步。

开发

pnpm install          # Install dependencies
pnpm build            # Build TypeScript + Swift binary
pnpm test             # Run full test suite
pnpm lint             # Lint and format (Biome + TypeScript)
pnpm dev              # Run from source via tsx

生产入口点（bin/run.cjs）需要 pnpm build。本地开发使用 pnpm dev。

架构

flowchart LR
    Client[MCP Client<br/>Claude Code, Cursor, Desktop] -->|stdio| Server[macos-mcp]

    Server --> Swift[Swift CLI]
    Server --> JXA[JXA]
    Server --> SQLite[SQLite Readers]

    Swift -->|EventKit| Reminders[Reminders]
    Swift -->|EventKit| Calendar[Calendar]

    JXA -->|Apple Events| Notes[Notes]
    JXA -->|Apple Events| Contacts[Contacts]
    JXA -->|writes only| Mail[Mail]
    JXA -->|send only| Messages[Messages]

    SQLite -->|Envelope Index| Mail
    SQLite -->|chat.db| Messages
    SQLite -->|AddressBook| Enrich[Contact<br/>Enrichment Cache]

通向 Apple 应用的三种桥接：

• EventKit（Swift 二进制）。 Reminders、Calendar。编译后的 Swift CLI，返回 JSON。

• JXA。 Notes、Mail 写入、Contacts。通过 osascript -l JavaScript 运行的脚本。

• SQLite。 Messages 读取（~/Library/Messages/chat.db）、Mail 读取（~/Library/Mail/V10/MailData/Envelope Index）。JXA 读取消息在 Sonoma 及更高版本上已失效。JXA 读取邮件对真实收件箱来说太慢。

Mail 和 Messages 使用混合路径：写入用 JXA（触发发送/草稿的唯一方式），读取用 SQLite（唯一可扩展的方式）。架构决策记录见 DECISION.md。

依赖

运行时： @modelcontextprotocol/sdk、zod

开发： typescript、tsx、jest、@biomejs/biome

致谢

MCP 服务器层源自 FradSer/mcp-server-apple-events（MIT）。EventKit Swift CLI、SQLite 读取路径、联系人增强、预检检查和技能层均在此项目中新增。

许可证

MIT

贡献

见 CONTRIBUTING.md。