zenoti

Zenoti MCP 服务

适用于 Zenoti 水疗／健康护理／医美水疗管理平台的模型上下文协议（MCP）服务。它将预约、宾客、服务预订、发票、目录和表单作为 AI Agent 可调用的工具提供。

提供托管版本

不想自行管理凭据、托管和更新？DOCK 是此服务的托管版本：提供按诊所配置的加密身份验证、审计日志、优先保存草稿的写入操作，以及工作流库。创始诊所可锁定终身定价：前台 $49/月（Zenoti），账单台 $99/月（Tebra，包含 BAA），完整诊所 $129/月（两者均包含）。https://dockhq.vercel.app

安装

npm install -g zenoti-mcp-server

或从源代码运行：

git clone https://github.com/tacit-code/zenoti-mcp-server.git
cd zenoti-mcp-server
npm install
npm run build

配置

变量	必需	说明
ZENOTI_API_KEY	是	从 Zenoti Admin → Settings → Apps 获取 API 密钥（创建后端应用）
ZENOTI_API_URL	否	基础 URL，默认为 https://api.zenoti.com（可带或不带 /v1）
ZENOTI_CENTER_ID	建议	默认中心 GUID；工具接受 center_id，可在每次调用时覆盖

Claude Desktop / Claude Code 配置：

{
  "mcpServers": {
    "zenoti": {
      "command": "npx",
      "args": ["-y", "zenoti-mcp-server"],
      "env": {
        "ZENOTI_API_KEY": "your_api_key",
        "ZENOTI_CENTER_ID": "your_center_guid"
      }
    }
  }
}

即使没有凭据，服务也会启动，并在每次工具调用时返回易读的配置错误，因此配置错误的客户端会显示问题，而不会陷入崩溃重启循环。

工具

目录

工具	用途
zenoti-centers-list	列出组织中心（查找中心 GUID）
zenoti-services-list	列出某个中心的服务（默认精简显示，使用 verbose 查看原始数据）
zenoti-services-get	获取完整的服务详情
zenoti-therapists-list	列出某个中心的理疗师，可按服务筛选
zenoti-employee-schedules	查询日期范围内的排班人员（按日期范围筛选人员）

宾客

工具	用途
zenoti-guests-search	按姓名／电子邮件／电话／代码／标签搜索（至少需要 1 个条件）
zenoti-guests-create	创建宾客档案
zenoti-guests-get	按 GUID 获取宾客详情
zenoti-guests-update	更新字段 — 执行安全的读取、合并和写入操作（Zenoti 更新时会替换整个对象）
zenoti-guests-appointments	获取宾客的预约历史
zenoti-guests-notes-list / zenoti-guests-notes-add	宾客备注和档案提醒
zenoti-guests-memberships	获取宾客的会员资格（状态、次数、应缴费用）
zenoti-guests-packages	获取宾客的套餐／疗程及剩余兑换次数

预约

工具	用途
zenoti-appointments-list	列出某个中心在指定日期范围内的预约（默认精简显示）
zenoti-appointments-get	获取预约详情（appointment_id）
zenoti-appointments-checkin / zenoti-appointments-undo-checkin	签到状态（appointment_group_id）
zenoti-appointments-noshow	标记为未到场（appointment_group_id）
zenoti-appointments-progress	开始／开启／完成服务（appointment_id）
zenoti-appointments-cancel	取消预订（按 invoice_id）
zenoti-appointments-reschedule	开始重新安排预约（创建与发票关联的预订草稿）

预订流程

1. zenoti-availability-slots — 为宾客、服务和日期创建预订草稿，并返回 booking_id 和可用时段
2. zenoti-booking-reserve — 保留选定的时段（保留时间较短）
3. zenoti-booking-confirm — 完成预订；响应中包含发票

发票

工具	用途
zenoti-invoices-get	获取包含明细项、付款记录以及可选应缴费用／手续费的发票
zenoti-invoices-pay-custom	记录现金／自定义付款（财务操作）
zenoti-invoices-pay-card	从宾客存档的银行卡扣款（财务操作）
zenoti-invoices-close	关闭已全额付款的发票
zenoti-invoices-email	将收据／发票通过电子邮件发送给宾客
zenoti-invoices-confirm-visit	确认（或撤销确认）到访 — 这是预约状态操作，尽管该工具归属发票类别

报表

工具	用途
zenoti-reports-sales	查询日期范围内售出的项目
zenoti-reports-collections	查询日期范围内收到的款项

表单与反馈

工具	用途
zenoti-forms-list / zenoti-forms-get	预约的表单及已提交的表单数据
zenoti-guest-forms-list	宾客资料中的表单
zenoti-feedback-submit	插入外部收集的宾客反馈

此服务处理的 Zenoti API 注意事项

• 一个工作流中有三个标识符。 签到／标记未到／反馈需要 appointment_group_id；详情／进度／表单需要 appointment_id；取消和付款需要 invoice_id。工具架构会注明所需的确切标识符。
• 更新宾客资料时会替换整个对象。 更新工具会获取当前资料并合并你的更改；直接进行部分 PUT 会清除其他字段。
• 速率限制为每分钟 60 次调用（组织级别）。HTTP 层会遵循 429 响应中的 Retry-After。读取操作也会在出现 5xx／网络故障／超时后重试；写入操作仅会在 429 时重试（速率限制拒绝请求时并未处理该请求，因此重试不会重复创建预约——其他写入失败都会立即返回）。
• 分页上限为 size=100；Zenoti 会以 422 拒绝更大的值。
• Webhook 没有订阅 API——需在 Zenoti 网页界面（Admin → Webhooks）中配置，且需要 Zenoti API 套餐。此服务有意不提供 Webhook 工具。
• 未公开的数字枚举值。 Zenoti 的公开文档未列出性别和预约进度代码；此处使用的映射记录在工具说明中，并且可以覆盖（progress_code）。

开发

npm run dev        # run from source (tsx)
npm test           # unit + end-to-end tests (mock Zenoti API; no real credentials needed)
npm run typecheck  # tsc --noEmit
npm run build      # emit dist/

端到端测试套件通过 MCP SDK 客户端，经由 stdio 启动真实服务，并针对 Zenoti 文档中记载的端点，验证每个工具的方法、路径、查询参数和请求体。

许可证

MIT