rotacloud-mcp-node

一个 MCP 服务器，将 RotaCloud API 暴露给 Claude 和其他 MCP 客户端。它覆盖了 36 个资源中的全部 129 个已记录的 v1 操作——班次、出勤、休假、用户、地点、角色、工时表等。

工具是根据 RotaCloud 发布的 OpenAPI 规范（vendor/openapi.json）生成的，因此参数名称、类型和描述直接来自文档。

安装

作为 Claude Desktop 扩展

下载 rotacloud-mcp-node.mcpb 并用 Claude Desktop 打开。系统会提示你输入 RotaCloud API 密钥，你可以从你的 RotaCloud 账户中生成。

手动安装 / 开发

npm install
export ROTACLOUD_API_KEY="your-api-key-here"
node server/index.js

将其添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "rotacloud": {
      "command": "node",
      "args": ["/absolute/path/to/rotacloud-mcp-node/server/index.js"],
      "env": {
        "ROTACLOUD_API_KEY": "your-api-key-here"
      }
    }
  }
}

配置

默认情况下，请求以具有管理员权限的匿名用户身份发出。设置 ROTACLOUD_USER_ID 后，每个请求都将改为以该用户身份执行。行为取决于操作用户的工具——me_*、messages_*、leave_requests_*、swap_requests_* 和 unavailability_requests_*——还接受 as_user 参数，以便在每次调用时覆盖该设置。

工具

工具命名为 {resource}_{action}，例如 shifts_list、shifts_create、users_retrieve、leave_requests_approve。

名称来源于 API 文档中每个操作的摘要，而不是其 HTTP 方法，因为在这个 API 中两者经常不一致——DELETE /users_clocked_in/{id} 将用户签退，POST /swap_requests/{id} 会拒绝换班。工具名称反映了操作的实际行为：users_clocked_in_clock_out、swap_requests_deny_shift_admin。

日期和时间

RotaCloud 混用三种格式，工具完全遵循 API 的格式：

• Unix 纪元秒用于班次和出勤时间（start_time、in_time，以及 /shifts、/attendance、/availability、/pay_periods 等上的 start/end 范围筛选器）。这些工具也接受 ISO 8601 字符串，并会为你进行转换。

• YYYY-MM-DD 字符串用于休假、日备注、TOIL 和用户日期（start_date、end_date、dob 等）。

• HH:MM 字符串用于日志簿事件时间和可用性时间窗口。

分页

列表端点接受 limit 和 offset 参数。分页的响应以如下格式返回：

{
  "meta": { "total_count": 137, "links": { "next": "…", "last": "…" } },
  "data": [ … ]
}

结果不会自动分页——每次调用仅返回一页，因此较宽的时间范围不会淹没上下文。请跟随 meta.links.next 或递增 offset 来翻页。

请求体

写操作工具会列出该端点文档中的每个字段，但也接受未知字段。RotaCloud 发布的请求体模式是从示例负载中提取的，对实际情况描述不足（例如 role_rates 在文档中使用示例里字面上的角色 ID 作为键），因此拒绝未文档化的字段会阻止有效的写入操作。每个写操作工具的描述中都包含文档化的示例负载。

资源

• accounts (1)

• attendance (5)

• attendance_approved (2)

• availability (2)

• day_notes (5)

• days_off (3)

• days_off_patterns (5)

• documents (6)

• groups (5)

• holiday_allowances (2)

• holiday_allowances_custom (3)

• leave (5)

• leave_embargoes (5)

• leave_requests (6)

• leave_types (1)

• locations (5)

• logbook_categories (5)

• logbook_events (5)

• me (2)

• messages (2)

• pay_periods (3)

• pins (1)

• roles (5)

• settings (1)

• shifts (5)

• shifts_acknowledged (1)

• shifts_published (2)

• swap_requests (5)

• terminals (5)

• terminals_active (3)

• timezones (2)

• toil_accruals (4)

• toil_allowance (1)

• unavailability_requests (6)

• users (5)

• users_clocked_in (5)

适用范围

此服务器覆盖 https://rotacloud-api-docs.netlify.app/ 上发布的 v1 API。RotaCloud 官方 Node SDK 暴露了一些额外的 v2 端点（发票、v2 日志簿、用户入职），这些端点不属于公开文档的一部分，因此不包含在此处。

重新生成

server/tools.js 是生成并提交的文件。要获取更新版本的 API：

curl -o vendor/openapi.json https://rotacloud-api-docs.netlify.app/openapi.json
npm run generate

如果两个操作会产生相同的工具名称，生成器会明确报错。

构建

npm run build   # mcpb pack

在分发生成的 .mcpb 之前，请检查其内容——mcpb pack 会将本地 dotfiles 一并纳入包中。

许可证

MIT