notesbridge

NotesBridge 是一个 Model Context Protocol（MCP）连接器，可让 ChatGPT 使用你的 Apple Notes。所有 Notes 操作都通过本地 Agent 在你自己的 Mac 上运行。请求的笔记内容会经由托管中继传输给 ChatGPT；任务参数和结果会临时存储在中继数据库中。

  ChatGPT  ──OAuth──►  NotesBridge relay  ──job queue──►  apple-notes-agent  ──►  Apple Notes.app
 (connector)          (Vercel, stateless)   (your Mac, polls & executes)         (on your Mac)

Agent 会在你的 Mac 上访问 Apple Notes。中继会存储账户记录和临时任务数据及结果；ChatGPT 会接收请求的笔记内容。受密码保护的笔记和附件内容不在已验证的读取范围内。

---

面向用户——3 步即可完成

1. 创建账户：前往 notesbridge.vercel.app 并生成配对码。

2. 安装 Mac Agent（需要 Node 18+）：

npx apple-notes-agent pair <YOUR-CODE>   # link this Mac to your account
npx apple-notes-agent install            # keep it running on every restart

首次访问 Notes 时，macOS 会询问 “Terminal 想要控制 Notes”——点击 “好”（仅需一次）。

**3. 连接 ChatGPT：**前往 Settings → Plugins → 开启 Developer mode（位于 Security & login）→ Create 自定义插件 → 粘贴 MCP Server URL https://notesbridge.vercel.app/mcp → 选择 Authentication OAuth → 登录并点击 Allow。

完成。在新聊天中输入：“搜索我的 Apple Notes，查找 Q3 规划笔记”，或 “创建一条标题为 Groceries 的笔记，内容为牛奶、鸡蛋、咖啡。”

你的 Mac 必须保持唤醒，且 Agent 正在运行。npx apple-notes-agent install 会让它在登录时自动启动，并在崩溃后自动重启。

管理 Agent

npx apple-notes-agent status      # is it paired & reachable?
npx apple-notes-agent logs        # recent activity
npx apple-notes-agent uninstall   # stop auto-start

在此源代码检出目录中，如需创建本地私有文本索引（Node.js 22.13+），请运行 node agent/cli.mjs index-install。该命令会每批索引 25 条笔记，并每 15 分钟检查一次更改。index-status 会报告覆盖率。 搜索会先检查当前 Notes 元数据，再使用缓存文本；如果索引已过期， 则回退到实时 Notes。受密码保护的内容和附件内容不会纳入索引。SQLite 索引保存在 Mac 上仅所有者可访问的目录中，位于仓库之外。 索引命令可在源代码中使用；npm 发布与此分开。

---

ChatGPT 可以执行的操作

工具	操作
search	按关键词搜索笔记
fetch / get_note	读取笔记的完整内容
list_folders	列出文件夹及笔记数量
list_notes	列出笔记（可按文件夹筛选）
create_note	创建新笔记
append_to_note	向笔记追加文本
update_note	重写笔记（具有破坏性——ChatGPT 会先确认）

---

自行托管

你可以运行自己的中继，从而不依赖托管实例。

**前提条件：**一个 Vercel 账户和一个 Supabase 项目（免费套餐即可）。

1. 存储——在 Supabase 项目的 SQL 编辑器中运行 supabase/schema.sql。它会创建一个精简的 Redis 风格 KV + 队列接口（nb_* 函数），并启用 RLS。
2. 部署 server/ 目录到 Vercel。
3. 设置环境变量（参见 server/.env.example）：
   • SUPABASE_URL、SUPABASE_SERVICE_ROLE_KEY——你的项目和 service-role 密钥
   • JWT_SECRET——openssl rand -hex 32
4. 验证：curl https://YOUR-APP.vercel.app/api/health → redisConfigured、redisOk、jwtSecretSet 均为 true。
5. 将 Agent 指向该服务：npx apple-notes-agent pair <CODE> --server https://YOUR-APP.vercel.app。

---

工作原理

• 身份验证 — 使用 PKCE 和动态客户端注册（RFC 7591）的 OAuth 2.1。ChatGPT 会注册自身，用户在 NotesBridge 授权页面登录，然后 ChatGPT 获得具有指定权限范围的 MCP 访问令牌。JWT 使用 HMAC 签名；分为三种类型（session、agent、mcp），权限各不相同。可选通过 Resend 验证邮箱（RESEND_API_KEY）；未配置时默认关闭，且需选择启用强制验证（REQUIRE_EMAIL_VERIFICATION）。
• 中继 — MCP 工具调用 → 作业推送至 jobs:<user>（TTL 不超过调用方的等待时长，因此被放弃的作业不会延迟执行）→ Mac Agent（保持长轮询挂起）在约 200ms 内收到作业并执行，然后推送结果 → MCP 处理程序返回结果。长轮询意味着作业到达时即会送达，而不是按固定间隔轮询，因此中继开销约为 300ms，而非约 1s。只有在 Agent 处于活动连接状态时，才会被视为“在线”。
• Agent — 无依赖的 Node CLI。工具通过 JXA（osascript -l JavaScript）操作 Notes.app；参数以 JSON 形式通过 argv 传递（绝不通过 shell 插值）。macOS LaunchAgent 会在登录后及崩溃后让它保持运行。

仓库结构

server/    Vercel functions: OAuth + MCP endpoint + relay        (deploy this)
agent/     apple-notes-agent — the npm-published Mac CLI          (users npx this)
kit/       Browser automations: register the dev-mode connector AND
           fill the OpenAI directory submission (see kit/README.md)
supabase/  schema.sql for self-hosting the storage
test/      end-to-end OAuth + MCP integration test

开发

# server
cd server && cp .env.example .env.local   # fill in, then: vercel dev
# end-to-end test against a live deployment (reads ../.env.local)
node test/e2e-oauth.mjs
# agent unit tests
node --test agent/test-agent-unit.mjs

安全与隐私

• 仅在你的 Mac 上读取/写入备忘录。中继绝不持久化备忘录内容——作业载荷存储在类似 Redis 的存储中，设置较短的 TTL，并会在送达后删除。
• Agent 令牌存储在 ~/.notesbridge-agent.json（权限模式 600）。
• 不会提交任何密钥；请参阅 .gitignore 和 .env.example 文件。
• 写入工具被标记为具有破坏性，因此 ChatGPT 会在覆盖内容前询问。

许可证

MIT © Isaiah Dupree

完整读取覆盖范围

list_notes 和 search 会返回 next_cursor。持续传入该值，直到其为 null；即使搜索结果页为空，也可能仍有游标。列表按稳定的备忘录 ID 顺序排列。搜索会报告跳过的受密码保护备忘录。授予 Notes 自动化权限后，运行 node test/live-all-notes.mjs，即可进行只读的本地覆盖范围测试。当前验证状态见报告。