messages-bridge

MessagesBridge 是一个 Model Context Protocol（MCP）连接器，可让 ChatGPT 使用你的 iMessage 对话和通讯录。读取操作通过一个轻量的本地 Agent 在你自己的 Mac 上执行。请求的结果会经过托管中继服务，再返回给 ChatGPT。中继服务会在队列中临时存储请求和结果载荷；它不会永久保存你的消息历史记录。

  ChatGPT  ──OAuth──►  MessagesBridge relay  ──job queue──►  apple-messages-agent  ──►  Messages.app + Contacts
 (connector)          (Vercel, stateless)      (your Mac, polls & executes)        (on your Mac)

你的消息只会在自己的 Mac 上读取，联系人也只会在自己的 Mac 上写入。中继服务仅存储短期有效的任务载荷和你的账户记录；只有任务正在处理中时，它才会接触到消息，队列载荷也会在较短时间后过期。

---

用户指南 — 3 个步骤

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

2. 安装 Mac Agent（需要 Node 18+ 和 Apple Command Line Tools）：

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

Agent 需要获得两项 macOS 权限，只需授权一次：完全磁盘访问权限，以便读取你的消息历史记录（系统设置 → 隐私与安全性 → 完全磁盘访问权限）；以及自动化权限，在它首次发送消息或读取通讯录时使用——macOS 会询问 “终端想要控制‘信息’”以及是否允许访问通讯录；点击**“好”**。

3. 连接 ChatGPT：设置 → 插件 → 开启开发者模式（安全与登录）→ 创建自定义插件 → 粘贴 MCP 服务 URL https://messagesbridge.vercel.app/mcp → 身份验证选择 OAuth → 登录并点击允许。

完成。在新聊天中输入：“搜索我的消息，查找晚餐计划”或“给 Sarah 发短信，说我会晚 10 分钟。”（每次发送前都需要你确认。）

你的 Mac 必须保持唤醒状态，并运行 Agent。npx apple-messages-agent install 会让它在登录时自动启动，并在意外崩溃时重新启动。

管理 Agent

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

---

ChatGPT 可以做什么

工具	操作
search_messages	搜索纯文本和 Apple 属性文本；即使结果页为空，也要继续使用 next_cursor
list_recent_threads	按时间从新到旧列出最近的对话，并显示最后一条消息的预览
get_thread	使用精确的聊天 ID 分页读取单个对话；将 next_cursor 作为 cursor 传入，直到其值为 null
messages_status	检查本地访问权限、数量和覆盖范围，但不返回消息内容
send_message	向一位收件人发送 iMessage（需先由你确认，不支持批量发送）
search_contacts	按姓名查找联系人（返回其电话号码和电子邮件地址）
get_contact	按姓名或 ID 读取一位联系人的信息
create_contact	添加联系人（姓名，以及可选的电话号码或电子邮件地址）

读取操作优先；只有 send_message 和 create_contact 是写入工具，且每次运行前都需要你在 ChatGPT 中确认。发送始终一次只发给一位收件人，绝不批量发送。

---

自托管

你可以运行自己的中继服务，这样就无需依赖托管实例。

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

1. 存储 — 在 Supabase 项目的 SQL 编辑器中，运行 supabase/schema.sql。它会创建相互隔离的 actp_messagesbridge_* 表和 mb_* 存储函数，并启用 RLS 和仅限服务角色的授权。
2. 部署 server/ 目录到 Vercel。
3. 设置环境变量（参见 server/.env.example）：
   • SUPABASE_URL、SUPABASE_SERVICE_ROLE_KEY — 你的项目地址和服务角色密钥
   • JWT_SECRET — openssl rand -hex 32
4. 验证： curl https://YOUR-APP.vercel.app/api/health → redisConfigured、redisOk、jwtSecretSet 均为 true。
5. 让 Agent 指向该服务：npx apple-messages-agent pair <CODE> --server https://YOUR-APP.vercel.app。

---

工作原理

• 身份验证 — 使用 PKCE 和动态客户端注册（RFC 7591）的 OAuth 2.1。ChatGPT 会自行注册，用户在 MessagesBridge 授权页面登录，随后 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 命令行工具。读取类工具会直接查询 Messages 的 chat.db（只读 SQLite）；发送和联系人类工具通过 JXA（osascript -l JavaScript）操作 Messages.app 和 Contacts；参数以 JSON 格式通过 argv 传递（绝不通过 shell 插值）。macOS LaunchAgent 会让它在登录后持续运行，并在崩溃后自动恢复。

仓库结构

server/    Vercel functions: OAuth + MCP endpoint + relay        (deploy this)
agent/     apple-messages-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 上进行。中继会在任务/结果队列中临时保存请求的内容，并设置较短的 TTL；结果送达后即会被取用。
• Agent 令牌存储在 ~/.messagesbridge-agent.json（权限模式为 600）。
• 不会提交任何机密；参见 .gitignore 和 .env.example 文件。
• 写入类工具标记为具有破坏性，因此 ChatGPT 会在发送消息或添加联系人之前征求确认——每次发送都只会发给一位已确认的收件人，绝不会批量发送。

许可证

MIT © Isaiah Dupree

已验证的读取覆盖范围和实时测试

Agent 1.1 会读取实时 SQLite WAL，使用 macOS Foundation 解码 Apple 富文本，并提供有界游标分页。游标遵循数据库插入顺序。仅包含附件的记录仍可通过 has_attachments 查看；附件文件不会上传或解码。Mac 数据库是覆盖范围的边界：这并不能证明每条 iPhone/iCloud 消息都已同步。

apple-messages-agent doctor
node test/live-messages.mjs
# After pairing your own account and starting the agent:
MB_EMAIL=your-email MB_PASSWORD=your-password node test/live-relay.mjs

请通过安全的环境提供凭据，不要放在共享的对话记录或已提交的文件中。实时测试只会读取并打印汇总结果。live-messages 会检查本地的每个对话分页、最大会话中的所有消息、解码后的搜索结果以及游标验证。live-relay 会验证实际的 OAuth、MCP 和配对 Mac 读取；如果 Mac 处于离线状态，测试会失败。绝不接受审核者/演示输出作为实时集成的证据。

生产环境需要完成存储迁移并配置有效的 Supabase。存储不可用时，/api/health 会返回 HTTP 503。如果旧中继数据库不可用，则无法自动恢复其中的账户、配对信息和 OAuth 会话；请登录/创建所有者账户并重新连接插件。