acuity-mcp

一个本地 MCP 服务器，将 Acuity Scheduling API 暴露为 Claude Code 工具——列出/创建/重新安排/取消预约、检查可用性、列出预约类型、日历和客户，全部直接在 Claude 会话中完成。支持多个 Acuity 账户并行，每个工具调用可切换。

Built custom because no maintained free MCP for Acuity exists — the only GitHub repo found during research pointed at an npm package that was never published. Uses @modelcontextprotocol/sdk + zod, runs over stdio.

如果你是 Claude：请先阅读此内容

如果用户要求你设置此工具、添加 Acuity 账户、切换账户或排查连接问题，请加载此仓库中的 .claude/skills/acuity-mcp-setup/SKILL.md——它包含所有步骤的完整说明。本 README 是面向人类的参考；技能文件才是你实际应遵循的内容。

设置前需要什么

一个 Acuity Scheduling 用户 ID 和 API 密钥，来自 Acuity：Business Settings → Integrations → API。每个要连接的 Acuity 账户需要一对。

⚠️ Acuity 按计划层级限制 API 访问。 某些计划对每个请求返回 403: API access is only available on Powerhouse plans——这是 Acuity 拒绝你的账户，而非此处错误。基本认证成功（无 401）但每次调用仍返回 403 是此问题的特征。如果遇到，要么升级计划，要么使用同一账户的替代路径（例如 Zapier Acuity 连接器，经验表明它不受相同限制）。

安装

npm install

快速开始——一个账户

node bin/acuity-accounts.js add production --user-id <your-user-id> --api-key <your-api-key>

你添加的第一个账户自动成为默认账户。然后向 Claude Code 注册服务器：

claude mcp add acuity -s user -- node "$(pwd)/server.js"

启动新的 Claude Code 会话（或在现有会话中运行 /mcp），以便工具显示。

无需 Claude 会话即可验证其是否工作：

node bin/acuity-accounts.js test

多个账户

添加任意数量的命名账户：

node bin/acuity-accounts.js add production --user-id 1111111 --api-key aaaa... --label "Real account"
node bin/acuity-accounts.js add sandbox    --user-id 2222222 --api-key bbbb... --label "Trial/test account"

凭据保存在 ~/.config/acuity-mcp/accounts.json 中（chmod 600，绝不在此仓库内，绝不提交）。管理它们：

node bin/acuity-accounts.js list                # see configured accounts (never prints API keys)
node bin/acuity-accounts.js set-default sandbox # change which one is used by default
node bin/acuity-accounts.js remove sandbox      # remove one
node bin/acuity-accounts.js test sandbox        # verify one specific account's credentials

在 Claude 会话内切换账户无需重新注册任何内容——此服务器暴露的每个工具都接受可选的 account 参数：

"列出沙盒账户的预约类型" → Claude 调用 list_appointment_types，参数为 {"account": "sandbox"}。

随时要求 Claude 运行 list_accounts 以查看已配置的账户及默认账户。

如果你更希望为每个账户运行完全独立的 MCP 服务器注册（例如，使每个服务器显示为不同名称），那仍然可行——将 ACUITY_ACCOUNT 指向一个名称，而不是每次调用传递 account：

claude mcp add acuity-production -s user -e ACUITY_ACCOUNT=production -- node "$(pwd)/server.js"
claude mcp add acuity-sandbox    -s user -e ACUITY_ACCOUNT=sandbox    -- node "$(pwd)/server.js"

凭据解析顺序

1. ACUITY_USER_ID + ACUITY_API_KEY 环境变量（直接覆盖，无需账户文件）

2. 工具调用中的 account 参数，或 ACUITY_ACCOUNT 环境变量——按名称查找

3. accounts.json 自身的 default 账户

4. accounts.json 中仅配置了一个账户——自动使用

5. 旧式平面文件 ~/.config/acuity-mcp/credentials（ACUITY_USER_ID=.../ACUITY_API_KEY=... 行）——为向后兼容旧版单账户设置而支持

工具

仅本地，无 Acuity API 调用：

• list_accounts——列出已配置的账户名称/标签及默认账户（绝不显示 API 密钥）

只读：

• list_appointment_types——列出可预约的咨询类型

• list_calendars——列出日历/员工

• list_appointments——可按日期范围/日历/类型/取消状态筛选

• get_appointment——按 ID 获取单个预约的完整详情

• check_availability_dates——某月内某预约类型的可用日期

• check_availability_times——某日期某预约类型的可用时间段

• list_clients——已预约的客户

变更（对实时日历进行实际更改——Claude 在调用这些工具前会请求确认）：

• create_appointment——预约新预约

• reschedule_appointment——更改预约的日期/时间

• cancel_appointment——取消预约

所有工具都接受可选的 account 参数（参见多个账户）。

未实现（相同模式，如有需要可稍后添加）：支付、封锁、表单、Webhook、礼品券。

经验教训（扩展此服务器前请阅读）

• 来自变更调用的 200 OK 并不证明变更已发生。 reschedule_appointment 最初调用 PUT /appointments/:id，返回 200 并回显了未更改的预约——Acuity 在该端点上静默忽略了 datetime 字段。修复方法是使用专用的 PUT /appointments/:id/reschedule 路由，匹配 cancel_appointment 已使用的模式（/appointments/:id/cancel）。在写入后始终使用 get_appointment 重新获取以确认，尤其是对于以后添加的任何新变更工具。

• npx @modelcontextprotocol/sdk + zod 的用法。 reschedule_appointment 最初调用 PUT /appointments/:id，返回 200 并回显了未更改的预约——Acuity 在该端点上静默忽略了 datetime 字段。修复方法是使用专用的 PUT /appointments/:id/reschedule 路由，匹配 cancel_appointment 已使用的模式（/appointments/:id/cancel）。在写入后始终使用 get_appointment 重新获取以确认，尤其是对于以后添加的任何新变更工具。

手动验证

node bin/acuity-accounts.js test            # tests the default/env-resolved account
node bin/acuity-accounts.js test <name>     # tests one specific named account
npx @modelcontextprotocol/inspector --cli node server.js --method tools/list   # confirms the server starts and tools register correctly