zola-mcp

Zola MCP

一个 Model Context Protocol 服务，可将 Claude 连接到 Zola，让你通过自然语言访问婚礼供应商、预算、宾客名单、座位表、活动、礼品登记表、咨询信息等。

警告

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

你可以做什么

你可以向 Claude 提出这些问题：

• “婚礼筹备进展如何？”
• “在北卡罗来纳州夏洛特市找一位摄影师”
• “将场地费用更新为 $25,000”
• “还有谁没回复 RSVP？”
• “把 Pat 安排在 1 号桌”
• “有新的供应商消息吗？”
• “把我的表亲 Mike 加入宾客名单”
• “给我看看礼物追踪表”

要求

• Claude Desktop 或 Claude Code
• Node.js 22 或更高版本
• 一个 Zola 账户
• 如不使用环境变量：ContextMint Bridge Chrome 扩展程序（目前尚不支持 Safari，请暂时使用 Chrome）

使用条款确认

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

1. 此服务访问的是你自己的 Zola 账户。 身份验证使用你自己的凭据。它不会，也无法访问其他人的婚礼网站、礼品登记表或宾客名单。

2. Zola 的使用条款适用于你对本服务的使用，正如这些条款也适用于你直接使用 zola.com。与此最相关的条款如下：

[你不得使用] 任何旨在秘密拦截或以其他方式获取任何信息的硬件或软件……包括但不限于使用任何“抓取”或其他数据挖掘技术、机器人或类似的数据收集和提取工具。

至关重要的是，关于 Agent 代表你行事的条款：“你有责任对自己的账户和密码保密……你对在你的账户和密码下发生的所有活动承担全部责任，即使此类操作是由你的授权 Agent 或其他第三方执行的。”

每次调用此服务中的工具时，你都同意这些条款——维护者于 2026-05-23 阅读过这些条款。Zola 的使用条款明确指出：此 MCP 作为你的授权 Agent 行事，视同你本人行事。

3. 仅限个人非商业用途。 本项目与 Zola, Inc. 无关联，未获其认可或赞助，也未与其建立合作关系。这是一款供一对新人管理自家婚礼网站、礼品登记表、供应商调查和宾客名单的个人自动化工具。请勿用它批量提取 Zola 的供应商目录、抓取礼品登记表，或与 Zola 竞争。

4. 不保证稳定性。 此服务可能会调用 Zola 的内部端点，而这些端点可能随时变更。服务可能因此无法运行。

5. 你对使用此服务访问 Zola 账户所产生的任何后果承担全部责任，包括速率限制、账户警告、暂停或任何强制措施。根据 Zola 的使用条款，此 MCP 在你的账户下执行的任何操作都视为你的操作——请在确认前检查宾客名单编辑、礼品登记表变更和咨询信息。如果 Zola 对你的使用提出异议，请停止使用此服务。

本节是维护者本着诚信对条款的概述；它不构成法律建议，也不会修改或取代 Zola 的实际使用条款。

安装

选项 A — MCPB（推荐）

从 Releases 下载最新的 .mcpb 捆绑包并安装：

claude mcp add-from-mcpb zola-mcp-x.y.z.mcpb

系统会提示你输入 ZOLA_REFRESH_TOKEN（请参阅下文的获取刷新令牌）。

选项 B — npm

npx -y zola-mcp

添加到你的 Claude 配置（.mcp.json 或 Claude Desktop 配置）：

{
  "mcpServers": {
    "zola": {
      "command": "npx",
      "args": ["-y", "zola-mcp"],
      "env": {
        "ZOLA_REFRESH_TOKEN": "your-refresh-token-jwt"
      }
    }
  }
}

选项 C — 从源代码安装

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

添加到 Claude Desktop 配置：

• Mac： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zola": {
      "command": "node",
      "args": ["/absolute/path/to/zola-mcp/dist/bundle.js"],
      "env": {
        "ZOLA_REFRESH_TOKEN": "your-refresh-token-jwt"
      }
    }
  }
}

获取刷新令牌

你有两种选择。两种方式都会生成相同的 usr Cookie 值——一个约 1 年有效的 JWT，同时也用作刷新令牌。

选项 A — ContextMint Bridge（推荐）

1. 安装 ContextMint Bridge——Chrome：从最新版本下载 Chrome 压缩包，解压后在 chrome://extensions 中以未打包的形式加载（开启开发者模式）。Safari 暂不可用（它将随 ContextMint 应用一起发布，目前该应用没有公开下载方式），因此请暂时使用 Chrome。

   ContextMint Bridge 是 fetchproxy 浏览器扩展的新名称，维护者相同——fetchproxy 自己的 README（fetchproxy#extension）也指向它。其源代码公开于 nullnet-app/contextmint-bridge：你可以自行构建，也可以将发布压缩包与随附的 .sha256 文件进行校验（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。

2. 在该浏览器中登录 zola.com/account/login。

3. 在 Claude 配置中将 ZOLA_REFRESH_TOKEN 留空。

首次调用工具时，MCP 会通过 chrome.cookies.get 向扩展请求 HttpOnly usr Cookie，然后由 Node 直接调用 API——Bridge 不会处于关键调用路径中。

该 Cookie 是约 1 年有效的刷新令牌，因此会缓存到 $MCP_DATA_DIR/.zola-mcp/refresh-token.json（如果该变量未设置，则使用 $HOME，权限模式为 0600）。之后启动时会从该路径读取，无需使用浏览器，这也使服务能够在没有浏览器的远程主机上运行。如果 API 拒绝缓存的令牌——例如你已退出登录，或令牌已超过一年有效期——令牌会自动丢弃，并再次向扩展请求。要重新验证身份，只需重新登录 zola.com。设置 ZOLA_TOKEN_CACHE=false 可避免在磁盘上保存任何内容，并在每次需要时都向浏览器请求。

你可以通过设置 ZOLA_DISABLE_FETCHPROXY=1 停用此回退方式（例如在没有可用扩展的无头或 CI 环境中）。

选项 B — 手动获取（DevTools）

1. 在任意浏览器中登录 zola.com/account/login。
2. 打开 DevTools → Application → Cookies → https://www.zola.com。
3. 复制 usr Cookie 的值。
4. 将其粘贴到 .env 中，写作 ZOLA_REFRESH_TOKEN=<value>（或粘贴到 Claude 配置的 env 块中）。

重启 Claude Desktop

完全退出（Mac 上按 Cmd+Q），然后重新启动。

验证

向 Claude 提问："婚礼筹备进展如何？"——它应该会显示你的婚礼仪表板。

凭据

环境变量	必需	说明
ZOLA_REFRESH_TOKEN	有条件	刷新令牌 JWT（有效期约 1 年）。未设置时，MCP 会回退到 ContextMint Bridge 浏览器扩展，从已登录 zola.com 的标签页中读取 usr Cookie。
ZOLA_DISABLE_FETCHPROXY	否	设置为 1 可选择停用 fetchproxy 回退（无头环境 / CI）。不会停用令牌缓存——无头运行仍可复用先前引导时缓存的令牌，因为读取文件并不等于打开浏览器。
ZOLA_TOKEN_CACHE	否	设置为 false 可停用磁盘上的刷新令牌缓存，并在每次启动时询问浏览器。默认启用；设置 ZOLA_REFRESH_TOKEN 时，此项不生效。
ZOLA_TOKEN_FILE	否	缓存文件的绝对路径。默认使用 $MCP_DATA_DIR/.zola-mcp/refresh-token.json，否则使用 $HOME/.zola-mcp/refresh-token.json。
ZOLA_ACCOUNT_ID	否	首次使用时从 API 自动解析
ZOLA_REGISTRY_ID	否	首次使用时从 API 自动解析
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	否	确认令牌的签名密钥（默认值：每个进程随机生成）。仅当令牌需要在服务重启后仍然有效时才设置。

可用工具

12 个领域共提供 77 个工具。权限列说明调用与变更之间需要经过什么步骤：

• 自动 — 只读；无需询问即可运行。
• 宿主提示 — 写入操作。会在非只读工具运行前询问你的客户端（Claude Code、Claude Desktop）会先征求你的同意；服务本身不会询问，因此在没有提示的客户端（claude.ai）上，首次调用便会执行。
• 服务端门控 — 无法撤销或会改变宾客所见内容的写入操作，因此服务会在每个客户端上自行确认。

由服务端门控的写入操作包括 remove_guest、update_event、update_wedding_settings、remove_faq、remove_home_section、remove_poi、remove_travel_item、remove_registry_item、set_event_guests 和 remove_event_invitation（仅当 set_event_guests 会取消任何人的邀请时）。每项操作都会先显示预览，注明相关家庭、活动、条目或页面内容，并准确说明变更内容（更改 slug 时会显示网站的旧 URL 和新 URL；对于私人或受密码保护的礼品清单中的条目，或默认合集以外的条目，会按 ID 显示，因为只有公开页面会显示其名称），然后仅在你批准后继续——请参阅上文的 MCP_CONFIRM_MODE。

供应商

工具	功能	权限
list_vendors	列出所有已预订的供应商	自动
search_vendors	按名称 / 类别搜索供应商	自动
add_vendor	预订新供应商	宿主提示
update_vendor	更新供应商详情	宿主提示
remove_vendor	取消预订供应商	宿主提示

预算

工具	功能	权限
get_budget	包含所有条目的预算摘要	自动
update_budget_item	更新费用或备注	宿主提示

宾客

工具	功能	权限
list_guests	列出所有宾客组及统计信息——默认包括姓名、级别和 RSVP 状态；view: "full" 会额外显示地址、电子邮件和电话号码	自动
add_guest	添加宾客组	主办人提示
update_guest_address	更新邮寄地址	主办人提示
remove_guest	移除宾客组（以及其 RSVP 和席位）	服务端门控

座位安排

工具	功能	权限
list_seating_charts	列出座位表	自动
get_seating_chart	获取包含桌位、座位和就座宾客的座位表	自动
list_unseated_guests	列出尚未安排座位的宾客	自动
assign_seat	为宾客安排座位	主办人提示

咨询

工具	功能	权限
list_inquiries	列出所有供应商咨询及其状态	自动
get_inquiry_conversation	获取完整的对话消息	自动
mark_inquiry_read	标记为已读	主办人提示

活动与 RSVP

工具	功能	权限
list_events	列出所有活动及 RSVP 计数	自动
track_rsvps	按活动跟踪 RSVP	自动
get_gift_tracker	查看收到的礼物及致谢状态	自动
get_registry	获取礼物清单中的商品及各商品的购买状态（requested_qty、purchased_qty、marked_fulfilled、availability、inconsistent）；通过 limit/offset 分页	自动
update_event	更新活动详情	服务端门控
set_event_guests	设置受邀参加某活动的宾客组（批量）	服务端门控
invite_guest_to_event	邀请单个宾客或宾客组参加某活动（仅添加邀请，不影响其他活动）	主办人提示
remove_event_invitation	移除对单个宾客或宾客组的活动邀请	服务端门控

礼物清单与礼物

工具	功能	权限
search_registry_products	浏览指定类别中的 Zola 商品，范围限定为你的礼物清单	自动
add_registry_item	按 SKU 将商品添加到礼物清单	主办人提示
update_registry_item	更新现有礼物清单商品——必须提供所有字段（会完整替换）	主办人提示
remove_registry_item	从宾客可购买的礼物清单中移除商品	服务端门控
reconcile_registry	将礼物清单与礼物跟踪记录关联：DUPLICATE_RISK（已标记为履行，但尚未购买——仍可购买）、UNATTRIBUTED（已购买但没有订单，因此送礼人和金额信息丢失）、ORPHAN_ORDER、MATCHED	自动

婚礼网站 — 页面与设置

工具	功能	权限
list_pages	列出婚礼网站的所有页面及其 ID、类型、显示顺序、可见性和主题信息	自动
set_page_hidden	在婚礼网站上显示或隐藏页面（例如，在发出邀请前隐藏 RSVP 页面）	主办人提示
reorder_pages	调整网站导航中的页面顺序	主办人提示
update_page	更新页面级元数据（标题、简介、导航标题、可见性、布局自定义设置）	主办人提示
get_wedding_settings	获取顶层婚礼设置：标题、URL 别名、伴侣姓名、日期、城市、主题标签、宾客人数、搜索可见性	自动
update_wedding_settings	更新顶层婚礼设置	服务端门控

婚礼网站 — 内容（常见问题、首页、游玩推荐、旅行）

工具	功能	权限
list_faqs	列出婚礼网站上的所有常见问题	自动
add_faq	在网站常见问题页面添加新的常见问题（问题 + 答案）	主办方提示词
update_faq	更新现有常见问题 — 必须提供全部三个字段（question、answer、display_order）	主办方提示词
remove_faq	从公开网站移除常见问题	服务端限制
list_home_sections	列出网站首页上的故事版块	自动
add_home_section	在首页添加故事版块（标题 + 副标题 + 描述文本块）	主办方提示词
update_home_section	更新首页故事版块 — 必须提供所有字段	主办方提示词
remove_home_section	从公开首页移除故事版块	服务端限制
list_pois	列出“游玩推荐”页面上的兴趣点	自动
add_poi	在“游玩推荐”页面添加兴趣点（餐厅、景点等）	主办方提示词
update_poi	更新兴趣点	主办方提示词
remove_poi	从公开的“游玩推荐”页面移除兴趣点	服务端限制
list_travel_items	列出网站“旅行”页面上的酒店、航班和交通信息	自动
add_travel_item	在“旅行”页面添加旅行项目（酒店、航班、火车、汽车、巴士）	主办方提示词
update_travel_item	更新旅行项目	主办方提示词
remove_travel_item	从公开的“旅行”页面移除旅行项目	服务端限制

婚礼网站 — 主题

工具	功能	权限
get_current_theme	获取当前选中的网站主题：键、名称、色板颜色、布局类型	自动
get_website_customizations	获取当前的网站颜色、字体设置以及可用的字体和颜色选项	自动
search_themes	浏览可用婚礼网站主题目录	自动
update_current_theme	将婚礼网站切换为其他主题模板	主办方提示词
update_website_customization	更新网站颜色和字体	主办方提示词

请柬与预留日期卡

工具	功能	权限
list_card_projects	列出你的请柬／预留日期卡／迎婴派对请柬「卡片」项目（纸质或数字版）	自动
get_card_project	获取一个请柬项目的完整详情，包括所有自定义设置（请柬、信封、RSVP 卡、详情卡）、纸张／颜色选项，以及每项自定义内容对应的页面	自动
validate_card_project	验证请柬项目——报告每项自定义内容中任何文字适配、图片或宾客地址相关错误	自动
get_card_project_guests	列出分配给请柬项目的宾客组，包括印刷地址的各组字号覆盖设置	自动
get_card_suite	获取请柬设计「套系」（一组搭配的请柬、RSVP 卡和详情卡）的详情，包括纸张类型、尺寸和价格范围	自动
search_card_catalog	搜索请柬设计目录	自动
list_favorite_card_suites	列出你收藏（点心形图标）的请柬设计套系	自动
get_rsvp_page	获取婚礼网站上的 RSVP 页面设置（标题、引言文案、可见性、自定义设置）	自动
create_card_project	根据设计套系和主选变体（特定尺寸／纸张）创建新的请柬项目	主机提示词
swap_card_project_variation	将项目中的一项或多项自定义内容替换为其他变体（纸张类型、颜色或尺寸）	主机提示词
set_card_project_guests	为请柬项目启用／停用宾客组，并可选择覆盖印刷姓名和地址的字号	主机提示词
preview_card_template	渲染请柬模板预览并填入文本	自动
preview_qrcode	为请柬生成 QR 码 PNG 图片	自动
set_card_project_qrcode	在请柬项目的指定页面放置或更新 QR 码	主机提示词

发现与运行状况

工具	功能	权限
zola_healthcheck	验证凭据和 Zola 的连通性；指出失败的环节	自动
get_wedding_dashboard	婚礼筹备仪表板概览	自动
search_storefronts	按类别／地点搜索市场	自动
get_storefront	获取商家店铺的完整详情	自动
list_favorites	已收藏的商家	自动

故障排除

“Zola auth: set ZOLA_REFRESH_TOKEN, or install the ContextMint Bridge extension…” —— 在配置中设置 ZOLA_REFRESH_TOKEN，或安装 ContextMint Bridge 扩展并登录 zola.com。

“Zola session refresh failed” —— 刷新令牌已过期（约 1 年）或已被撤销。请获取新的 usr cookie（DevTools），或在安装 ContextMint Bridge 扩展后重新登录 zola.com。

移动 API 返回 403 —— 可能缺少 x-zola-session-id 标头。请更新到最新版本。

Claude 中未显示工具 —— 前往 Claude Desktop → Settings → Developer 查看已连接的服务。编辑配置后，请确保完全退出并重新启动。

安全

• 刷新令牌仅保存在本地 .env 或配置文件中（如果已设置），或保存在用户的浏览器 Cookie 存储中（fetchproxy 路径）
• 刷新令牌通过环境变量传递，且绝不会记入日志
• 服务使用与 iOS 应用相同的流程，通过 Zola 的移动 API 进行身份验证
• 账号和注册表 ID 会从 API 自动解析（无需手动配置）

开发

npm test        # run the test suite (vitest)
npm run build   # compile TypeScript → dist/

项目结构

src/
  client.ts               Zola mobile API client (auth, token refresh, context)
  index.ts                MCP server entry point
  tools/
    index.ts              TOOL_REGISTRARS — every tool module the server registers
    vendors.ts            list, search, add, update, remove vendors
    budget.ts             get budget, update budget items
    guests.ts             list, add, update, remove guests
    seating.ts            seating charts, seat assignment
    inquiries.ts          vendor inquiry conversations
    events.ts             events, RSVPs, gift tracker, registry
    event-invitations.ts  which guests are invited to which events
    registry-items.ts     registry item add / update / remove
    reconcile-registry.ts registry vs gift-tracker reconciliation
    website.ts            website pages and wedding settings
    website-content.ts    FAQs, home sections, things to do, travel
    website-theme.ts      website theme and customizations
    invitations.ts        invitation / save-the-date card projects
    discover.ts           dashboard, storefront search, favorites
    healthcheck.ts        zola_healthcheck
tests/                    one *.test.ts per module, plus manifest/docs/annotation sync tests

身份验证流程

所有工具都使用 Zola 移动 API（mobile-api.zola.com）并通过 Bearer JWT 进行身份验证：

1. 使用刷新令牌 JWT 调用 POST /v3/sessions/refresh → 返回有效期为 30 分钟的会话令牌
2. 所有 API 调用都使用 Authorization: Bearer <session_token> 和 x-zola-session-id 标头
3. 收到 401 时，自动刷新并重试一次
4. 会话令牌会在其有效期内缓存（30 分钟）

构建 MCPB 包

推送版本标签时，Release 工作流 会自动构建 .mcpb 包。要在本地构建：

npm run build
npx @anthropic-ai/mcpb pack

此操作会使用 manifest.json 中的配置生成 zola-mcp.mcpb。该包包含编译后的 dist/bundle.js，以及用于配置 ZOLA_REFRESH_TOKEN 的用户提示词。

发布

发布通过 GitHub Actions 自动完成：

1. 运行 Cut & Bump 工作流（手动触发）——为当前版本打标签并递增修订号
2. 推送标签会触发 Release 工作流，该工作流会：
   • 运行 CI（构建 + 测试）
   • 打包 .skill 和 .mcpb 包
   • 发布到 npm
   • 创建包含这些包的 GitHub Release

许可证

MIT