Apple Notes

Name: Apple Notes
Author: mgcrea

本地服务

cupertino.mgcrea.io生产力5今天更新

代码仓库访问官网

关于 Apple Notes

Apple Notes 的 MCP 服务，通过 Apple Events 与只读 SQLite 索引读取 Mac 上的笔记；写入工具默认关闭，并可在需要时单独启用。

主要功能

01搜索笔记与查看内容
02浏览账户、文件夹和附件
03保存附件
04写入工具默认关闭

适用场景

01按关键词查找笔记
02读取笔记及附件信息
03启用写入工具管理笔记

MCP 相关

向 MCP 客户端提供 Apple Notes 的搜索、读取和附件工具；设置 APPLE_NOTES_ALLOW_WRITES=1 后才会注册新增、更新、移动和删除工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "mgcrea-mcp-apple-notes": {
      "command": "npx",
      "args": [
        "-y",
        "@mgcrea/mcp-apple-notes"
      ],
      "env": {
        "APPLE_NOTES_ALLOW_WRITES": "<APPLE_NOTES_ALLOW_WRITES>",
        "APPLE_NOTES_ACCOUNTS": "<APPLE_NOTES_ACCOUNTS>"
      }
    }
  }
}

启动命令npx -y @mgcrea/mcp-apple-notes

需要配置的环境变量

APPLE_NOTES_ALLOW_WRITESRegister the mutating tools. Off by default, and the gate decides whether the write tools exist at all rather than merely refusing — an agent with writes off cannot see them.

APPLE_NOTES_ACCOUNTSRestrict every read and write to these Notes accounts, by name.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@mgcrea/mcp-apple-notes1.31.0stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

@mgcrea/mcp-apple-notes

适用于 macOS Apple Notes 应用的模型上下文协议服务。

非官方。 与 Apple 无关联。它操作的是 Mac 上已安装的 Notes 应用。

两条路径

Apple Events 路径 — 账户、文件夹、正文和所有修改操作。始终以此为准：写入后，结果以 Notes 重新读取的内容为准。
索引路径 — 通过 NoteStore.sqlite 以只读方式访问 SQLite，用于搜索和获取元数据，处理 Apple Events 无法胜任的大规模数据。需要完全磁盘访问权限。

与 Mail 不同，仅使用 Apple Events 路径就能让服务正常工作。在包含 921 条笔记的资料库中进行测试，全文搜索耗时 97 ms，而 Mail 因此改用索引搜索，耗时 74 s。因此，你可以先安装并使用，之后再决定是否授予完全磁盘访问权限。

不过它无法无限扩展：底层没有索引，每次查询都要重新付出全部成本。瓶颈大约在 5–10k 条笔记。apple_notes_diagnostics 会告诉你当前由哪条路径响应。

权限	用途	未授予时
自动化 → Notes	所有功能	所有功能都无法使用；会出现 `-1743` 错误
完全磁盘访问权限	大规模搜索、`save_attachment`	服务仍可通过 Apple Events 路径运行

这两项权限都不是授予 Notes.app 的——需要权限的是 读取数据的程序。

工具

读取：diagnostics、list_accounts、list_folders、list_notes、search_notes、get_note、 list_attachments、save_attachment。

写入：仅当 APPLE_NOTES_ALLOW_WRITES=1 时才会注册——关闭此标志时，这些工具对模型不可见，而不只是遭到拒绝：create_note、update_note、move_note、delete_notes、 add_attachment。

add_attachment 是在笔记中添加图片的唯一方式。在笔记正文中添加 <img> 标签会创建附件，但 Notes 永远不会加载其字节数据——详见 docs/notes.md。

配置

变量	默认值
`APPLE_NOTES_ALLOW_WRITES`	off	注册会修改数据的工具。
`APPLE_NOTES_ACCOUNTS`	all	读取端允许列表，以逗号分隔。
`APPLE_NOTES_INDEX_MODE`	`auto`	`auto` \| `ro` \| `immutable` \| `off`。
`APPLE_NOTES_STORE`	auto	显式指定 `NoteStore.sqlite` 路径。
`APPLE_NOTES_SEARCH_CACHE_TTL_MS`	`60000`	正文语料保持热缓存的时长。
`APPLE_NOTES_ATTACHMENT_DIR`	`~/Downloads`	附件唯一允许保存到的目录。
`APPLE_NOTES_BODY_MAX_BYTES`	`262144`	正文截断上限，用于保护上下文窗口。
`APPLE_NOTES_OSASCRIPT_TIMEOUT_MS`	`30000`	为首次运行时的权限提示预留的超时时间。

这些注意事项可能会让你踩坑

Notes 会将笔记正文的第一行作为标题。 设置 name 会被静默忽略，因此 create_note 会将标题作为标题行插入正文开头。
完全无法读取受密码保护的笔记。 其文本以 AES 密文形式静态存储，因此 ZICNOTEDATA 包含加密相关列；任何权限都无法让它变得可读。
文件夹可以嵌套。 即使你的资料库恰好是平铺的，文件夹映射也必须递归处理。
搜索缓存按 TTL 更新，而非通过失效机制更新。 通过 Apple Events 检查缓存是否过期要花费更多时间（128 ms），不如直接重新扫描（97 ms），因此接受有限的过期数据才是诚实的取舍。详见 docs/notes.md。