Apple Notes MCP Server

什么是 Apple Notes MCP Server？

Apple Notes MCP Server（RafalWilinski 开发的 mcp-apple-notes）是一个本地运行的 apple notes mcp server，让 Claude 可以搜索、读取和创建你的 Apple 备忘录，并通过端侧嵌入模型实现语义搜索和 RAG。

它是社区开源项目，并非 Apple 官方产品。它通过 JXA（JavaScript for Automation）从备忘录应用读取笔记，用 all-MiniLM-L6-v2 模型生成嵌入向量，并把向量存储在你 Mac 上的 LanceDB 中。整个过程不需要 API key，也不依赖云服务，所以你可以用自然语言询问笔记内容，由 Claude 找出相关笔记。请注意，该仓库自 2024 年 12 月以来没有更新，多个未关闭的 issue 报告了安装问题（见常见问题排查）。

如何使用 Apple Notes MCP Server？

前提条件：一台装有 Apple 备忘录应用的 Mac、Bun，以及 Claude Desktop 等 MCP 客户端。

克隆仓库并安装依赖：

git clone https://github.com/RafalWilinski/mcp-apple-notes
cd mcp-apple-notes
bun install

Claude Desktop

1. 打开 Claude Desktop，进入 Settings → Developer → Edit Config。
2. 在 claude_desktop_config.json 中添加一项，用 Bun 运行 index.ts：

{
  "mcpServers": {
    "apple-notes": {
      "command": "/Users/<YOUR_USER_NAME>/.bun/bin/bun",
      "args": ["/Users/<YOUR_USER_NAME>/mcp-apple-notes/index.ts"]
    }
  }
}

把 <YOUR_USER_NAME> 替换为你的 macOS 用户名，并确认路径与仓库的克隆位置一致。README 示例中的文件夹名是 apple-notes-mcp，但 git clone 创建的是 mcp-apple-notes；仓库中有未关闭的 issue 指出了这个不一致。

3. 重启 Claude Desktop，确认服务器显示为已连接。
4. 搜索之前，先让 Claude "Index my notes" 或 "Index my Apple Notes"。根据笔记数量，索引可能需要几秒到几分钟。

Claude Code

README 只介绍了 Claude Desktop。Claude Code 可以运行同样的 stdio 命令：

claude mcp add apple-notes -- /Users/<YOUR_USER_NAME>/.bun/bin/bun /Users/<YOUR_USER_NAME>/mcp-apple-notes/index.ts

Cursor 等其他 MCP 客户端可以在 mcpServers 配置中使用相同的 command 和 args。macOS 可能会要求你允许启动该服务器的应用控制备忘录。

Apple Notes MCP Server 的主要功能

• 使用端侧 all-MiniLM-L6-v2 嵌入模型对 Apple 备忘录进行语义搜索。
• 在向量搜索之外还支持全文搜索。
• 使用 LanceDB 进行本地向量存储。
• 通过 JXA 原生访问 Apple 备忘录，无需导出。
• 可以从 Claude 创建笔记（create-note 工具）。
• 完全本地运行，无需 API key。
• 代码库小巧，基于 TypeScript，直接用 Bun 运行。

Apple Notes MCP Server 工具

服务器在 index.ts 中注册了五个工具：

• 索引： index-notes 读取所有笔记并建立语义搜索索引。请首先运行它，并在新增大量笔记后再次运行。
• 查找笔记： search-notes 利用索引按标题或内容搜索；list-notes 只返回所有笔记的标题。
• 读取： get-note 按标题返回笔记的完整内容和详情。
• 写入： create-note 根据标题和内容创建新笔记。该工具要求内容为不含换行的 HTML。

Apple Notes MCP Server 的使用场景

• 回忆内容："What did I write about the Q3 offsite?"，由你自己的笔记来回答。
• 找回旧片段："Find the note where I saved the router setup steps."
• 总结某个主题："Summarize everything in my notes about the kitchen renovation."
• 用于 RAG 的个人知识库：让 Claude 基于你的笔记而不是通用知识来回答。
• 从对话中记录："Save this meeting summary as a new note called 'Weekly sync'."

Apple Notes MCP Server 与替代方案对比

• 其他 apple notes mcp server 项目：一些社区服务器通过 AppleScript 驱动备忘录应用，并增加了文件夹支持或编辑、删除操作。这个仓库也有一些 fork，例如 Dan8Oren/mcp-apple-notes（文件夹支持和 bug 修复），以及 connerkward/mcp-apple-notes（直接读取备忘录数据库，而不是使用 JXA）。选择前请先确认它们的维护状态。
• Obsidian MCP Server：如果你的笔记是 Obsidian vault 中的 Markdown 文件，而不是在 Apple 备忘录里，它更合适。
• Notion MCP Server (Official)：适用于保存在 Notion 中的笔记和文档，由厂商维护。

Apple Notes MCP Server 常见问题排查

• 服务器无法启动：检查 args 路径是否指向 index.ts 的真实位置（克隆后的文件夹是 mcp-apple-notes），以及 command 是否指向你的 Bun 可执行文件（~/.bun/bin/bun）。
• 查看日志：运行 tail -n 50 -f ~/Library/Logs/Claude/mcp.log，或查看同一文件夹中该服务器专属的 mcp-server-<name>.log。
• 索引超时：有未关闭的 issue 报告，笔记很多时 index-notes 的耗时可能超过 Claude Desktop 的请求超时时间。如果反复出现，有社区 fork 报告索引速度大幅提升。
• JXA 报错：部分用户报告 run-jxa 依赖在较新的 macOS 版本上失效。请在系统设置中确认启动服务器的应用被允许自动化控制备忘录；如果问题持续，可以考虑仍在维护的 fork。
• 搜索不到最近的笔记：再次让 Claude "index my notes"，以便为新笔记生成嵌入。