Planday → Excel、Power BI 和 Claude

Planday 的 Timesheet Report——也就是包含每班次工作小时数和员工成本的那份报表——没有单一的 API 端点。大多数人都是碰了钉子才发现这一点的：把 Power Query 接错了对象，结果只拿回整整 50 行数据。

这个项目同时解决了这两个问题：

1. 一个转换器（translator），从 Planday 从不合并的三个端点组装出真正的 Timesheet Report，并以实时数据流的形式提供给 Excel 或 Power BI。

2. 一个 MCP 服务器，覆盖整个 Planday API——全部 125 个操作——让你可以用日常英语提问：“7 月份，按部门统计，外聘代班人员花了我们多少钱？”

MIT 许可证。运行在你自己的基础设施上。你的 Planday 凭据绝不会离开它。

尚未在真实门户上得到验证。 这里的所有内容都能在贴近真实的示例门户上运行，API 客户端也是根据 Planday 自己发布的规范生成的，但还没有人把它接到真实数据上。如果你打算这么做，请先阅读 TESTING.md——它解释了如何与 Planday 自带的报告进行核对，并如实说明这个项目最可能在哪些地方出错。里面有一个 pnpm doctor 命令，它逐层检查，能区分真正的 bug 与配置问题。

只想尽快让它跑起来？

→ SETUP.md 是分步指南，写给负责排班的人而不是开发者看的。 大约 20 分钟，无需编码，免费运行。

部署之后，在浏览器中打开它就会看到这个页面——它会告诉你哪些配置已完成，运行一次真实的测试提取，并为你生成一段已经填好你自己 URL 的 Power Query 片段：

本文件的其余部分面向开发者。

要求： Node 20 或更高版本，仅此而已。pnpm 与 lockfile 匹配，但使用 npm install 也完全没问题。

下面的所有内容都运行在贴近真实的示例数据上。不需要 Planday 凭据就能看到它的运行效果——这是判断它是否符合你需求的最快方式。

pnpm install && pnpm dummy      # or: npm install && npm run dummy

Planday timesheet  mode=dummy  2026-06-01 -> 2026-07-26

department                  shifts   worked h        cost   cost/h
------------------------------------------------------------------
Events                         160     1137.5   £21398.45    18.81
Kitchen                        167     1159.8   £21169.29    18.25
Front of House                 166     1116.1   £20793.30    18.63
Housekeeping                   133      942.6   £18243.15    19.35
------------------------------------------------------------------
TOTAL                          626     4356.1   £81604.19    18.73

rows: 626   cost source: payroll   portal: Harbour Group
edge cases -> orphan punch-clock: 1, open shifts: 1, no cost attached: 30, edited after approval: 22

626 rows - well past the 50-record cap that catches most people out.

两件让所有人踩坑的事

1. 没有 Timesheet Report 端点

https://openapi.planday.com/api/absence 及其同类链接都是文档页面，而不是 API 端点——这是一个很容易犯的常见错误。而且 Absence 是 Planday 的假期与加班核算功能，与考勤工时表无关。

Timesheet Report 是对三个端点做连接（join）得到的：

另外还需要 hr/departments、hr/employees、hr/employeegroups 和 scheduling/shifttypes 来把 id 转换为名称。这个连接逻辑位于 src/timesheet/transform.ts。

2. 50 条记录的上限

Planday 的列表端点在其规范中把 limit 声明为 maximum: 50。调大它毫无作用——服务器会默默地忽略你。唯一的办法是在 offset 上循环，直到取够 paging.total 条记录。

这里有个有用的转折：上面三个报告端点根本不分页。 它们是批量按日期范围调用的。所以只要你用对了端点，50 条记录的问题基本上就消失了——它从来只影响那些很小的查找表。

还有一点值得了解

每个 Planday 请求都需要两个请求头，而不是一个：

Authorization: Bearer <access token>
X-ClientId: <client id>

缺少 X-ClientId 会得到一个 401，看起来和令牌无效一模一样。访问令牌也会在一小时后过期，因此任何定时任务都必须刷新令牌——这在很大程度上解释了为什么用纯 Power Query 做这件事很麻烦，也是下面这个桥接服务存在的原因。

Related MCP server: TimeChimp MCP Server

把数据接入 Excel 或 Power BI

有两条路可选。它们适合不同的预算，而且都包含在项目中。

方案 A——桥接服务（推荐）

一个轻量服务夹在 Planday 和 Excel 之间。它负责 OAuth、每小时的令牌刷新以及所有分页逻辑，于是 Power Query 就只需要一次 Web.Contents 调用。

cp .env.example .env      # set BRIDGE_KEY
pnpm bridge

打开 http://localhost:8787 即可看到设置页面：它会显示已配置的内容，运行一次测试提取，并给你一段已经填好你自己 URL 的 Power Query 片段。

这个端点承载工资和薪金数据，所以从第一个提交起就要求认证——共享密钥放在 x-bridge-key 请求头中。无论设置如何，它都会直接拒绝所有写操作：一个电子表格可以刷新的 URL，绝不能有能力改动正在使用的排班表。

方案 B——完全不需要服务器

powerquery/Timesheet-direct.pq 从 Power Query 内部直接与 Planday 对话，其中包含解决 50 条记录问题的 List.Generate offset 循环。速度较慢，而且每次刷新都要重新认证，但运行成本为零。

MCP 服务器

19 个工具，覆盖全部 125 个 Planday 操作。

pnpm mcp        # stdio; .mcp.json already registers it for Claude Code

对 Claude Desktop，请把以下内容添加到 claude_desktop_config.json （macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\\Claude\\）：

{
  "mcpServers": {
    "planday": {
      "command": "pnpm",
      "args": ["--dir", "/absolute/path/to/planday-bridge", "tsx", "apps/mcp/index.ts"],
      "env": {
        "PLANDAY_CLIENT_ID": "your-client-id",
        "PLANDAY_REFRESH_TOKEN": "your-refresh-token",
        "PLANDAY_WRITE_TIER": "read"
      }
    }
  }
}

把那两个 Planday 值完全省略，即可针对示例门户运行。

注册 125 个相互独立的工具会让大多数 MCP 客户端不堪重负，而且在提出第一个问题之前，光是工具描述就会消耗数万个上下文 token。因此，覆盖面是完整的，但注册是分层的：

通用访问——3 个工具，覆盖全部 125 个操作

• planday_search_operations —— 按关键字查找任意端点

• planday_describe_operation —— 查看端点的完整签名和响应结构

• planday_call —— 调用端点，按规范校验，自动处理分页

Planday 能做到的任何事情都可以在这里触达，包括那些还没人想到过的端点。

精选只读——12 个工具，覆盖最常见的路径：部门（departments）、员工（employees）、员工组（employee groups）、班次类型（shift types）、职位（positions）、班次（shifts）、打卡记录（punch-clock entries）、缺勤记录（absence records）、工资单（payroll）、时间与成本（time-and-cost）、排班历史（scheduling history），外加 planday_whoami。

组合工具——4 个工具，完成原始 API 单次调用做不到的事：planday_get_timesheet（三路连接）、planday_summarise_staff_cost、planday_export_timesheet_csv、planday_explain_columns。

为什么它能回答问题，而不只是返回数据

一个中等规模门户八周的数据就远超一千行。把原始 JSON 直接交给模型会耗尽它的上下文，还会引发算术错误。因此，聚合在服务器端完成：planday_summarise_staff_cost 按部门、员工、员工组、班次类型、天、周、成本来源或外聘与自有员工（agency-vs-own-staff）分组，只返回十几行。大型提取结果以文件路径的形式返回，绝不会内联输出。

写入安全

125 个操作中有 62 个会修改数据——包括删除班次和部门、为员工打卡上下班。这些操作可以被发现，但受到门控：

什么都不会隐藏——但一个面对实时排班门户的 LLM，绝不会因为意外而得到一个删除按钮。

上线使用

以上所有内容都不需要 Planday 凭据。当你想要真实数据时：

1. 在 Planday 中：Settings → Integrations → API Access → Create App。勾选 SETUP.md 中列出的权限范围，点击 Authorise，然后复制 Client ID 和 Refresh Token。尽量少勾选权限范围——参见 SECURITY.md。

2. 把它们以 PLANDAY_CLIENT_ID 和 PLANDAY_REFRESH_TOKEN 的形式写入 .env。

3. 运行 pnpm doctor

pnpm doctor 更进一步：它会分别检查环境、配置、连接、每一个 Planday 权限范围，然后执行一次真实的报告构建，这样你就能确切地看到是哪一层出了问题。它的输出不携带任何凭据或员工数据，可以放心分享。Planday 对每个区域分别设置门控，所以一个完全有效的令牌也可能在 payroll 上被拒绝；发生这种情况时，报告会降级为 time-and-cost，再降级为只有工时而没有成本，而不是直接失败。

不需要修改任何代码。示例环境和真实环境运行的是同一条代码路径。

Planday 提供带 API 访问权限的 30 天免费试用，并可根据请求发放开发者演示门户——这对于在不接触生产排班表的情况下测试集成非常有用。

它如何保持正确

整个客户端是从 Planday 自己的 OpenAPI 规范生成的，这些规范内置在 specs/ 目录中。手写的端点封装会在 Planday 一发布变更时就开始漂移；而生成的封装只需几秒钟就能重新生成。

pnpm gen     # 125 operations, 294 schemas. Asserts no duplicate ids, no unresolved refs.
pnpm test    # 32 tests
pnpm doctor  # diagnose a live connection, layer by layer

覆盖测试会调用全部 125 个操作中的每一个，并根据该操作自己的 schema 校验每个响应。正是这一点让“整个 API 都可用”成为一个经过验证的事实，而不是一句声明——而且如果 Planday 新增了一个端点，它会自动被覆盖，不需要记得更新任何清单。

test/deploy.test.ts 用 esbuild 打包真实的 serverless 入口点，并对各个路由进行测试，因为很多代码在 tsx 下能通过，但一旦打包就会出问题。

其余的测试针对那些会破坏手工编写的 Power Query 合并的用例，固定了连接规则：没有 shift id 的打卡记录、跨午夜的班次、结束早于开始的记录对、无薪休息扣除、有工时但无成本的月薪员工

其他 Planday 数据。 工时表只是开发得最完善的示例。125 项操作中的每一项都已经可以通过 planday_call 和 /api/ 路由访问——缺勤余额、收入、薪酬费率、打卡钟、员工历史。如果你想要另一个像工时表那样构建的报告，src/timesheet/ 就是可以复制的模式。

安全

部署之前，请先阅读 SECURITY.md。简要说明：刷新令牌能够访问薪资数据，且不会自行过期；任何内容都不会存储在任意位置；默认拒绝写入操作；并且有一个用于报告漏洞的私有渠道。

贡献

欢迎提交 issue 和 pull request。如果 Planday 更改了它们的 API：请将规范重新下载到 specs/，运行 pnpm gen，然后 diff 会精确显示变动的内容。

正在使用 AI 编码代理处理这个项目？AGENTS.md 就是为此编写的——它承载着领域知识和那些重新发现代价高昂的隐蔽陷阱。