使用说明
Apple Notes MCP服务器
MCP服务器，允许Claude（或任何MCP客户端）在macOS上读取Apple Notes。
为什么
Apple Notes没有API。此服务器使用AppleScript弥合了这一差距，因此您可以将Claude指向您的笔记，并获得组织分析、内容摘要和结构建议等内容，而无需手动复制粘贴。AppleScript仅适用于macOS，因此此服务器需要Mac。
数据模型
Apple Notes有三个看起来相似但行为不同的概念：
- 文件夹 --一个实际的容器。笔记只存在于一个文件夹中。
- 标签 --元数据通过
#hashtag在笔记正文中或通过标签选择器UI应用。一个笔记可以有很多标签。 - 智能文件夹 --用户创建的虚拟视图。按标签、日期、检查表状态或其他条件过滤笔记。不是容器——智能文件夹中的笔记仍然存在于它们的真实文件夹中。
AppleScript返回相同的文件夹和智能文件夹 class:folder 无法将它们区分开来。此服务器通过容器ID比较检测智能文件夹，并将其排除在 list_folders.
看 docs/data-model.md 了解完整细节：AppleScript怪癖、检测算法、标签解析管道和分隔符协议。
工具
| 工具 | 描述 | 输入 |
|---|---|---|
list_folders |
列出带有笔记计数的实际文件夹（实际容器） | 无 |
read_notes |
读取真实文件夹中的所有笔记（id、标题、正文、时间戳） | folder （字符串，必填）， id （字符串，可选） |
create_note |
在文件夹中创建新笔记 | folder （字符串，必填）， title （字符串，必填）， body （字符串，可选）， id （字符串，可选文件夹ID） |
delete_note |
按ID删除注释 | noteId （字符串，必填） |
move_note |
将笔记移动到其他文件夹 | noteId （字符串，必填）， folder （字符串，必填）， id （字符串，可选文件夹ID） |
为什么没有 update_note 工具
Apple Notes将嵌入式附件（图像、PDF、扫描件）和段落样式（标题、标题、副标题）存储为与HTML正文分离的内部元数据。AppleScript的 set body 是更新笔记内容的唯一方法，但它 永久性破坏 这两者：
- 嵌入式附件被切断 --图像和PDF成为空的“文件”占位符。这些文件可能仍然存在于磁盘上，但无法再链接回笔记。这是不可逆转的。
- 段落样式丢失 --所有样式行在样式选择器中都会恢复为“Body”，即使它们仍然以粗体/字体大小样式呈现。
- iCloud立即同步损坏 --所有设备都会收到破坏性的更改，无法撤消。
因为 set body 无法安全地修改笔记而不冒数据丢失的风险，此服务器故意不公开它。笔记可以创建、移动和删除，但不能就地更新。看 docs/data-model.md 了解完整的技术细节。
文件夹ID查找
list_folders 返回一个唯一的 id 对于每个文件夹。你可以通过这个 id 到 read_notes 以特定文件夹为目标。当 id 只要它优先于 folder 不过，对于查找 folder 始终是人类可读性所必需的。
当多个文件夹共享同一名称时，这很重要。Apple Notes可以跨多个帐户后端存储笔记，最常见的是iCloud，但也包括Microsoft Exchange。苹果和微软有着长期的集成，允许Apple Notes通过Exchange与微软的Sticky Notes服务同步。如果用户启用了两个后端，他们将有两个名为“Notes”的文件夹（每个帐户一个），只能通过ID区分。
为什么没有 list_tags 工具
AppleScript不会将标记作为注释上的属性公开。标签可以通过两种方式创建——键入为 #hashtag 在注释正文中，或通过UI标签选择器应用——只有键入的标签才会出现在正文中。没有可靠的方法以编程方式枚举笔记上的所有标签。此服务器不尝试标签解析，而不是提供不可靠的工具。看 docs/data-model.md 了解全部细节。
设置
npm install
添加到克劳德代码
claude mcp add apple-notes -- npx tsx /path/to/Apple-Notes-Mac-MCP-server/src/index.ts
使用MCP检查员进行测试
npm run inspector
在以下位置打开浏览器UI http://localhost:6274 在那里，您可以交互式地测试工具。
发展
npm test # run tests
npm start # start the server (stdio transport)
npm run inspector # test in browser
需求
- macOS（此服务器使用AppleScript，仅限macOS）
- Node.js 18+
- 第一次运行将提示自动访问Notes的权限
