用途
mcp-apple-notes 是一个 Model Context Protocol（MCP）服务器，用于在 Apple Notes 上实现语义搜索与 RAG（检索增强生成）。它适用于任何兼容 MCP 的客户端，例如 Claude Desktop、Cursor、Windsurf、Cline 等。
主要能力
- 语义搜索：使用 all-MiniLM-L6-v2 设备端嵌入模型对 Apple Notes 进行语义检索。
- 全文搜索：提供全文搜索能力。
- 文件夹支持：可列出文件夹、按文件夹浏览、在搜索时按文件夹过滤。
- 向量存储：使用 LanceDB 存储向量。
- 原生集成：通过 JXA（Apple 官方 JavaScript for Automation 脚本桥）与 Apple Notes 原生集成。
- 本地执行：完全本地运行，无需 API 密钥。
- 只读模式：可选的只读模式，用于安全探索。
使用方式
安装方式有两种：
- 从源码安装（推荐）：克隆仓库到本地，可检查源代码，了解在机器上执行的内容。前置条件为 Node.js（v18+）或 Bun。然后将服务器添加到 MCP 客户端配置中，把 /path/to/mcp-apple-notes 替换为克隆仓库的路径。可通过设置环境变量 MCP_APPLE_NOTES_READ_ONLY=1 启用只读模式。
- 通过 npx 快速启动：如果偏好零配置并信任已发布的 npm 包，可直接将配置添加到 MCP 配置中。
设置完成后，重启客户端，并要求 AI 助手“index my notes”即可开始。
各客户端配置说明：
- Claude Desktop：打开 Settings → Developer → Edit Config，将 JSON 配置粘贴到 claude_desktop_config.json，然后重启 Claude Desktop。
- Cursor：将 JSON 配置添加到 ~/.cursor/mcp.json（全局）或项目根目录的 .cursor/mcp.json。
- Windsurf：将 JSON 配置添加到 ~/.windsurf/mcp.json。
可用工具与验证
所有 Apple Notes 操作都是可在 index.ts 中检查的 JXA 调用。没有网络请求，没有后台同步，只有本地脚本桥调用。
只读模式下仅以下工具可用：index-notes、list-folders、list-notes、search-notes、get-note。
可启用详细日志，在执行前查看每个 JXA 调用（记录到 stderr）：
- CLI 标志：在 MCP 客户端配置的 args 中添加 --verbose。
- 环境变量：适用于支持 env 的客户端。
JXA 操作参考：所有操作都通过 Apple 的 JXA 脚本桥（Application('Notes')）进行。无直接文件系统访问，无网络调用。删除操作是非永久性的——笔记会进入“最近删除”，可在 30 天内恢复。
工具响应为 JSON 对象，采用一致的信封格式：
- 成功：{ "ok": true, "data": ... }
- 错误：{ "ok": false, "error": { "type": "...", "message": "..." } }
大多数面向笔记的响应现在包含稳定的 Apple Notes id，以便客户端在重命名和移动后安全跟踪笔记。
适用场景
需要在本机对 Apple Notes 进行语义检索、全文搜索、按文件夹浏览或过滤，并希望与 MCP 兼容客户端集成以实现 RAG 的场景。
限制
- 仅支持 Apple Notes，需在 Mac 上运行。
- 依赖 Node.js（v18+）或 Bun。
- 只读模式会禁用所有写操作。
- 删除的笔记进入“最近删除”，30 天内可恢复。
- 具体可用工具与配置细节以仓库文档为准；其他未在资料中说明的功能与收费情况暂未提供。
安全与透明
由于该服务器与私有 Apple Notes 交互，设计以绝对透明为目标，100% 在 Mac 上本地运行。无云、无遥测、无 API 密钥，数据不离开机器。使用 Apple 官方 JXA 脚本桥。嵌入在设备端通过 @huggingface/transformers 本地运行 all-MiniLM-L6-v2 模型。鼓励在接触笔记前阅读每一行代码（尤其是 index.ts）。GitHub 发布版包含 SHA-256 校验和，可验证下载的构件。
社区与支持
问题报告、想法、提问和展示均有对应渠道：Bug 提交 issue；功能想法在 Ideas 发起讨论；设置或集成帮助在 Q&A 提问；用其构建了有趣项目在 Show and tell 分享；关注 Announcements 获取更新。欢迎 PR，对于非琐碎更改，请先开 issue 或讨论以对齐方向。
致谢
最初基于 RafalWilinski/mcp-apple-notes。