honeybook-mcp

HoneyBook MCP

一个 Model Context Protocol 服务，可将 Claude 连接到 HoneyBook 客户门户，让你能够用自然语言访问婚礼供应商发送的合同和发票。

警告

AI 开发的项目。 此代码库由 Claude Code 构建并持续维护。没有人类审核过其实现。使用前请检查所有代码和工具权限。

你可以做什么

向 Claude 提出类似这样的问题：

• “粘贴你的魔法链接——我会连接到你的 HoneyBook 门户。”
• “显示所有尚未签署的合同。”
• “我下个月有哪些到期发票？”
• “总结一下 Silk Veil Events 的合同。”
• “给我一个签署摄影师合同的深层链接。”
• “策划师这个月给我发了什么？把清单读给我听。”
• “回复 Ivy 的上一条消息，询问彩排时间。”
• “我和策划师下次 Zoom 会议是什么时候？链接是什么？”
• “到目前为止我付了多少钱？还有多少未付？”

要求

• Claude Desktop 或 Claude Code
• Node.js 22 或更高版本
• 使用 HoneyBook 的婚礼供应商发送的魔法链接邮件
• ContextMint Bridge 浏览器扩展——在 Chrome 中，从发布页面下载 Chrome 压缩包并以解压缩的方式加载（chrome://extensions → 开发者模式 → 加载已解压的扩展程序）。目前尚未提供 Safari 版本（它将随 ContextMint 应用一起发布，但该应用目前没有公开下载），因此暂时请使用 Chrome。use_magic_link 用它从已登录供应商门户的标签页中获取会话快照。

条款确认

使用此 MCP 服务，即表示你确认并同意以下内容：

1. 此服务访问的是你自己的 HoneyBook 工作区。 每个请求都会通过 ContextMint Bridge 扩展，使用你本人已登录的浏览器会话发送。此服务不会也无法访问其他人的工作区。

2. 你使用此服务须遵守 HoneyBook 的服务条款，就像你直接使用 honeybook.com 时一样。与此处最相关的条款如下：

在使用本服务时，你不得进行或使用任何数据挖掘、机器人、抓取或类似的数据收集或提取方法。

此外，用户不得“修改、复制、嵌入、抓取、出租、租赁、出借、出售、分发本服务或服务内容，也不得基于本服务或服务内容创作衍生作品”。

每次调用此服务中的工具，即表示你同意这些条款——维护者于 2026-05-23 阅读了这些条款。HoneyBook 的服务条款广泛禁止数据挖掘和抓取；此 MCP 是未经官方认可的自动化工具，HoneyBook 并未为其授予例外。

3. 仅限个人单一业务使用。 本项目与 HoneyBook, Inc. 无关联，未获其认可或赞助，也不与其合作。它是一款个人自动化工具，供个人 HoneyBook 账户持有人操作自己的工作区。请勿代表其他业务使用此工具，请勿批量提取 HoneyBook 的目录或模板内容，也请勿在此基础上创建衍生 SaaS 产品。

4. 不保证稳定性。 此服务会调用 HoneyBook 的内部接口，而 HoneyBook 可能随时更改这些接口。此服务可能会失效。

5. 你须对使用此服务时与你的 HoneyBook 账户相关的任何后果承担全部责任，包括速率限制、账户警告、暂停或 HoneyBook 采取的任何执法行动。HoneyBook 能够检测自动化流量，且可能封锁你的 IP 或工作区。如果 HoneyBook 对你的使用提出异议，请停止使用此服务。

本节是维护者本着诚信对条款所作的概述，不构成法律建议，也不会修改或取代 HoneyBook 的实际服务条款。

安装

从源代码安装

git clone https://github.com/chrischall/honeybook-mcp.git
cd honeybook-mcp
npm install
npm run build

将以下内容添加到 Claude Desktop 配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "honeybook": {
      "command": "node",
      "args": ["/absolute/path/to/honeybook-mcp/dist/bundle.js"]
    }
  }
}

无需设置环境变量。以下可选变量可调整写入操作的确认方式，详见确认。

会话

HoneyBook 没有公开的客户门户 API。此 MCP 通过 ContextMint Bridge 浏览器扩展，复用你在浏览器中点击供应商的魔法链接后已有的身份验证状态。

一次性设置：

1. 从其发布页面安装 ContextMint Bridge：在 Chrome 中，加载解压后的 chrome zip。Safari 目前尚不可用（它将随 ContextMint 应用一同发布，但该应用没有公开下载渠道）——暂时请使用 Chrome。 ContextMint Bridge 是更名后的 fetchproxy 浏览器扩展，由同一位维护者开发——fetchproxy 自己的 README（fetchproxy#extension）提供了该扩展的链接。其源代码公开在 nullnet-app/contextmint-bridge：你可以自行构建，或使用旁边发布的 .sha256 文件校验发布 zip（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。
2. 在常用浏览器中点击每个供应商的魔法链接。这会让你登录其 *.hbportal.co 门户。

按供应商激活：

1. 确保供应商的门户标签页已打开（即其邮件中的魔法链接）。
2. 在 Claude 中，使用魔法链接 URL 调用 use_magic_link——该工具会要求 ContextMint Bridge 扩展从页面的 localStorage["HONEYBOOK_REACT_CURR_USER"] 中提取身份验证字段并生成快照，然后关闭 Bridge。标签页只需保持打开且已登录；不会从实时请求中读取任何内容。不会启动无头浏览器。
3. 所有其他工具默认使用最近激活的会话。多个供应商处于激活状态时，请明确传入 origin。

会话保存在内存中，并持久化到 ~/.honeybook-mcp/sessions.json（mode 0600），以便在 MCP 重启后继续使用。会话过期时，请重新运行 use_magic_link。

问卷（“flow”）链接

供应商可能会发送另一种不同格式的链接：

https://<vendor>.hbportal.co/flow/<flowId>?hash=…&userId=…

该链接不会让你登录门户。它会打开一个问卷，并存储该流程专用的凭据——HoneyBook 称之为弱身份验证——位置为 localStorage["HONEYBOOK_REACT_WEAK_AUTH_<flowId>"]。使用 use_flow_link 捕获该凭据，并使用 get_flow 读取。

这两种凭据会刻意分开保存，分别存放在两个文件和两个存储中：

	门户会话	流程凭据
捕获工具	use_magic_link	use_flow_link
链接格式	/app/link/resolve/…	/flow/<flowId>?hash=…
存储位置	~/.honeybook-mcp/sessions.json	~/.honeybook-mcp/flows.json
可读取内容	工作区、文件、发票、付款方式	该问卷

每个工具都会按名称拒绝另一种格式的链接；如果门户工具仅使用流程凭据运行，它也会直接说明这一点，而不是等到稍后才返回难以理解的 HoneyBook 错误。list_active_sessions 会分别报告这两种凭据。

get_flow 会执行与问卷页面相同的两个调用：先调用公开的 GET /api/v2/flow/<flowId>/minimal 获取供应商公司 ID，然后调用 GET /api/v2/client/flow/<flowId>/active?ctxc=<companyId>。如果第一个调用未返回公司 ID，它就会在此处停止并说明原因——不带 ctxc 调用 /active 会返回一个裸露的 400，看起来像是凭据过期。

需要注意的是：存储键中包含流程 ID，因此每份新问卷都会在已声明的 fetchproxy 作用域中生成一个新键。扩展会根据配对时批准的作用域进行限制，所以每份问卷都需要重新批准一次。这是扩展的正常工作，并非故障。

可用工具

与供应商交互的工具接受可选的 origin 参数（例如 https://acme.hbportal.co）。仅有一个会话处于活动状态时，系统会自动推断该参数。

工具	功能	权限
use_magic_link	从魔法链接 URL 捕获会话	确认
list_active_sessions	显示活动凭据，并按类型分类	自动
use_flow_link	捕获问卷（流程）凭据	确认
get_flow	读取一份问卷及其答案	自动
list_workspace_files	列出某个供应商的文件；可按类型筛选	自动
get_workspace_file	查看某个文件的完整详情	自动
get_workspace	工作区详情及状态标记	自动
list_payment_methods	已保存的付款方式（品牌、末 4 位、到期日期）	自动
sign_contract	获取用于在门户中签署的深层链接（确认后）	确认
pay_invoice	获取用于在门户中付款的深层链接（确认后）	确认
list_projects	列出你与某个供应商的项目及其工作区 ID	自动
get_project	项目详情：日期、地点、人员、自定义字段	自动
list_messages	列出工作区中的消息（或活动日志），按时间从新到旧排列	自动
get_message	查看一条消息的完整内容：正文、附件、送达状态	自动
send_message	通过门户发送消息或回复（确认后）	确认
mark_messages_seen	将动态消息标记为已读（读取本身不会自动执行此操作）	自动
list_meetings	列出已安排的会议及加入链接，按最新时间排序	自动
list_tasks	列出供应商分配给你的任务及数量	自动
list_notes	列出供应商分享的备注	自动
list_attachments	列出工作区中的零散图片、文件和书签	自动
list_payments	列出付款计划及已付／未付总额	自动

send_message 是唯一一个代表你执行操作的工具：它会创建与门户“活动”编辑器相同的 send_workspace_message 任务，并等待 HoneyBook 完成任务，因此供应商会收到一封普通的 HoneyBook 电子邮件。 在你确认之前，它只会预览收件人、主题和正文 — 参见确认。

确认

sign_contract、pay_invoice 和 send_message 在执行前会要求你确认。能够显示 MCP 确认提示的客户端（Claude Code）会显示提示。无法显示提示的客户端（claude.ai、Claude Desktop）上，首次调用不会执行任何操作，而是返回预览和一个 confirmToken；只有使用相同参数和该令牌再次调用，操作才会继续。令牌只能使用一次；如果两次调用之间令牌所覆盖的内容发生变化（文件标题、消息正文、工作区的收件人），令牌就会被拒绝。

变量	默认值
MCP_CONFIRM_MODE	ask-user	在无法显示确认提示的客户端（claude.ai、Claude Desktop）上，写入操作的处理方式。ask-user：分两步执行——首次调用不执行任何操作，而是返回预览和令牌；模型必须先在聊天中获得你的批准，然后才能使用令牌再次调用。auto：同样分两步执行，但模型查看预览后可以使用令牌。refuse：在此类客户端上拒绝写入操作。能够显示提示的客户端（Claude Code）始终会显示实际提示，除非 MCP_CONFIRM_ELICITATION=off。无法识别的值会按 refuse 处理。
MCP_CONFIRM_ELICITATION	on	off 表示不发送确认提示，因此所有客户端都会采用 MCP_CONFIRM_MODE 的处理方式。对于声明能够显示提示、但实际上从不显示的客户端，请设置此项（受控调用会挂起——opencode 2.0.x）。其他任何值都会保持为 on，并显示 stderr 警告。
MCP_CONFIRM_TTL_SECONDS	600	令牌的有效时长。
MCP_CONFIRM_SECRET	每个进程随机生成	签名密钥；只有在令牌必须在服务重启后继续有效时才设置。

故障排除

• “HoneyBook auth expired” — 在 Chrome 中重新打开供应商的 magic link，然后重新运行 use_magic_link。
• “No active HoneyBook session” — 先调用 use_magic_link。
• “No active HoneyBook portal session. N flow (questionnaire) credentials are active” — 你捕获的是 /flow/ 链接，但调用的工具需要客户端门户链接。使用 /app/link/resolve/… 链接运行 use_magic_link，或使用 get_flow 读取问卷。
• “that is a questionnaire (flow) link, not a client-portal link” — 对该链接使用 use_flow_link。
• “no auth hash for flow …” — 你传入的链接丢失了 ?hash= 参数（页面加载后会重写 URL）。请从供应商邮件中重新复制原始链接。
• 在 get_flow 中出现 “HoneyBook error 400 … NOT an auth failure” — 缺少必需的输入，并非凭据问题。通常是固定的 HONEYBOOK_API_VERSION 已过期：取消设置该变量，以便从 /api/gon 读取当前值。重新运行 use_flow_link 无济于事。
• “no context id for flow …” — HoneyBook 的公共 /minimal 路由未返回问卷读取所需的供应商公司 ID。这也不是凭据问题。
• “fetchproxy capture failed” — 安装 ContextMint Bridge，然后在该浏览器中打开供应商的 magic link。
• “fetchproxy capture timed out” — 扩展程序没有找到可读取的已登录门户标签页。打开供应商的 magic link，确认门户页面已加载，然后重试。
• “no confirmed browser session” — 扩展程序已连接，但尚未批准此 MCP。打开 ContextMint Bridge 弹出窗口，批准其中显示的配对码，然后重试。
• “this browser … cannot serve the … capability” — 你配对的浏览器缺少捕获操作所需的 API。MCP 或配对并没有问题，重试或重新批准也无济于事：请在提供该 API 的浏览器中运行（例如 Chrome）。
• “localStorage keys not in declared set” — MCP 现在读取的存储键不在现有配对的覆盖范围内。请参阅从 0.4.4 或更早版本升级。重试无济于事，这也不是版本问题。

从 0.4.4 或更早版本升级

0.4.5 需要在浏览器扩展中重新批准一次。 HoneyBook 将客户端门户会话从 localStorage["jStorage"] 移到了 localStorage["HONEYBOOK_REACT_CURR_USER"]，因此 0.4.5 会读取不同的存储键。扩展会在配对时批准 MCP 声明的作用域，因此已有的配对不包含新的键，每次捕获都会被拒绝，并显示：

localStorage keys not in declared set: HONEYBOOK_REACT_CURR_USER

要解决此问题，只需执行一次以下操作：

1. 打开 ContextMint Bridge 扩展弹出窗口。
2. 撤销 honeybook-mcp。
3. 重新运行 use_magic_link——会显示一个新的配对码。
4. 在弹出窗口中批准该配对码。你批准的是新的作用域。

其他一切都不变：~/.honeybook-mcp/sessions.json 中的现有会话仍可使用，只有在会话本身过期时才需要重新捕获。

安全性

• 会话在本地捕获——身份验证令牌不会离开你的计算机
• ~/.honeybook-mcp/sessions.json 的权限模式为 0600；目录的权限模式为 0700
• 写入工具（sign_contract、pay_invoice、send_message）会先要求你确认（请参阅确认）；sign_contract 和 pay_invoice 会返回门户深层链接，而不会在无头模式下签署或付款

开发

npm test        # run tests
npm run build   # tsc + esbuild bundle

许可证

MIT