MCP Apple Notes

一个 Model Context Protocol (MCP) 服务器，支持对你的 Apple Notes 进行语义搜索和 RAG（检索增强生成）。适用于任何兼容 MCP 的客户端，如 Claude Desktop、Cursor、Windsurf、Cline 等。

功能特性

• 🔍 使用 all-MiniLM-L6-v2 本地嵌入模型对 Apple Notes 进行语义搜索

• 📝 全文搜索能力

• 📂 文件夹支持 — 列出文件夹、按文件夹浏览、按文件夹过滤搜索

• 📊 使用 LanceDB 进行向量存储

• 🤖 适用于任何兼容 MCP 的客户端（Claude、Cursor、Windsurf、Cline 等）

• 🍎 通过 JXA 原生集成 Apple Notes

• 🔒 可选的 只读模式，安全探索

• 🏃♂️ 完全本地执行 — 无需 API 密钥

Related MCP server: MCP Apple Notes

安全与透明度

由于此服务器会与你的私有 Apple Notes 交互，因此其设计核心是绝对的透明度。它 100% 在你的 Mac 本地运行。

• 无云端，无遥测 — 无需 API 密钥，数据不会离开你的机器。

• 原生 Apple JXA — 使用 Apple 官方的 JavaScript for Automation 脚本桥。

• 本地嵌入 — all-MiniLM-L6-v2 模型通过 @huggingface/transformers 在本地运行。

• 可验证 — 强烈建议你在使用前阅读每一行代码（特别是 index.ts）。

• GitHub 发布版本 包含 SHA-256 校验和，以便你验证下载的制品。

安装与设置

选择适合你工作流的安装方法。

方法 1：从源码安装（推荐）

通过在本地克隆仓库，你可以检查源代码并确切了解机器上正在执行的操作。

先决条件： Node.js (v18+) 或 Bun

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

{
  "mcpServers": {
    "apple-notes": {
      "command": "bun",
      "args": ["run", "/path/to/mcp-apple-notes/index.ts"]
    }
  }
}

使用 NPM：

git clone https://github.com/Dan8Oren/mcp-apple-notes && cd mcp-apple-notes && npm install

然后将服务器添加到你的 MCP 客户端配置中。将 /path/to/mcp-apple-notes 替换为你克隆仓库的路径：

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-apple-notes/index.ts"]
    }
  }
}

提示： 想无风险尝试？启用 只读模式 以在探索时阻止所有写入操作。 "env": { "MCP_APPLE_NOTES_READ_ONLY": "1" }

方法 2：通过 npx 快速启动

如果你更喜欢零配置方式并信任已发布的 npm 包，可以直接将其添加到你的 MCP 配置中：

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@dan8oren/mcp-apple-notes"]
    }
  }
}

设置完成后，重启你的客户端并让 AI 助手 "index my notes"（索引我的笔记）即可开始。

各客户端说明

1. 打开 Settings → Developer → Edit Config

2. 将你选择的 JSON 配置粘贴到 claude_desktop_config.json 中

3. 重启 Claude Desktop

日志：

tail -n 50 -f ~/Library/Logs/Claude/mcp-server-apple-notes.log

# npm version:
claude mcp add apple-notes npx -- -y @dan8oren/mcp-apple-notes
# or from source:
claude mcp add apple-notes npx -- tsx /path/to/mcp-apple-notes/index.ts

将 JSON 配置添加到 ~/.cursor/mcp.json（全局）或项目根目录下的 .cursor/mcp.json。

将 JSON 配置添加到 ~/.windsurf/mcp.json。

可用工具

验证机制

每一个 Apple Notes 操作都是一个 JXA 调用，你可以在 index.ts 中检查。没有网络请求，没有后台同步 — 只有本地脚本桥调用。

只读模式

需要安全保障？启用只读模式以阻止所有写入操作 — 仅可使用搜索、列表和读取工具：

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@dan8oren/mcp-apple-notes"],
      "env": { "MCP_APPLE_NOTES_READ_ONLY": "1" }
    }
  }
}

启用后，仅以下工具可用：index-notes、list-folders、list-notes、search-notes、get-note。

详细模式

启用详细日志记录以在执行前查看每个 JXA 调用（记录到 stderr）：

CLI 标志 — 在你的 MCP 客户端配置参数中添加 --verbose：

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["--verbose", "-y", "@dan8oren/mcp-apple-notes"]
    }
  }
}

环境变量 — 针对支持 env 的客户端：

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@dan8oren/mcp-apple-notes"],
      "env": { "MCP_APPLE_NOTES_VERBOSE": "1" }
    }
  }
}

JXA 操作参考

所有操作均通过 Apple 的 JXA 脚本桥 (Application('Notes')) 进行。没有直接的文件系统访问，没有网络调用。delete 操作并非永久删除 — 笔记会进入“最近删除”，可在 30 天内恢复。

响应格式

工具响应是具有统一结构的 JSON 对象：

• 成功：{ "ok": true, "data": ... }

• 错误：{ "ok": false, "error": { "type": "...", "message": "..." } }

大多数面向笔记的响应现在都包含稳定的 Apple Notes id，以便客户端可以在重命名和移动操作后安全地跟踪笔记。

致谢

最初基于 RafalWilinski/mcp-apple-notes。