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 명령도 있습니다.

그냥 바로 작동시키고 싶으세요?

→ 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는 세 엔드포인트의 조인입니다:

여기에 hr/departments, hr/employees, hr/employeegroups, scheduling/shifttypes를 더해 ID를 이름으로 변환합니다. 그 조인은 src/timesheet/transform.ts에 있습니다.

2. 50개 레코드 상한

Planday의 목록 엔드포인트는 자체 사양에서 limit을 maximum: 50으로 선언합니다. 값을 올려도 아무 효과가 없습니다. 서버가 조용히 무시합니다. 통과하는 유일한 방법은 paging.total 레코드를 얻을 때까지 offset을 반복하는 것입니다.

유용한 반전: 위의 세 보고서 엔드포인트는 전혀 페이지네이션되지 않습니다. 이들은 대량 날짜 범위 호출입니다. 따라서 올바른 엔드포인트를 사용하면 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는 50개 레코드 문제를 해결하는 List.Generate 오프셋 루프를 포함하여 Power Query에서 Planday에 직접 연결합니다. 더 느리고 매번 새로 고칠 때마다 다시 인증하지만, 실행 비용은 들지 않습니다.

MCP 서버

Planday의 전체 125개 작업을 다루는 19개 도구.

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 클라이언트가 과부하되고, 질문 한 번 하기 전에 설명만으로 수만 개의 컨텍스트 토큰을 소모하게 됩니다. 따라서 표면은 전체이지만 등록은 계층화되어 있습니다:

범용 액세스 — 3개 도구, 전체 125개 작업

• planday_search_operations — 키워드로 엔드포인트 검색

• planday_describe_operation — 전체 시그니처와 응답 형태

• planday_call — 사양에 따라 검증된 호출, 페이지네이션 처리

Planday가 할 수 있는 모든 것은 여기에서 접근할 수 있으며, 아직 아무도 생각하지 못한 엔드포인트도 포함됩니다.

선별된 읽기 — 12개 도구 일반적인 경로를 위한 도구: 부서, 직원, 직원 그룹, 교대 유형, 직위, 교대, 출퇴근 기록, 결근 기록, 급여, 시간 및 비용, 스케줄링 기록, 그리고 planday_whoami.

복합 도구 — 4개 도구 원시 API가 한 번의 호출로 할 수 없는 작업을 수행합니다: planday_get_timesheet(3중 조인), planday_summarise_staff_cost, planday_export_timesheet_csv, planday_explain_columns.

데이터만 반환하지 않고 질문에 답할 수 있는 이유

중간 규모 포털의 8주 분량 데이터는 천 행이 훨씬 넘습니다. 이를 원시 JSON으로 모델에 넘기면 컨텍스트가 고갈되고 산술 오류가 발생하기 쉽습니다. 따라서 집계는 서버 측에서 이루어집니다. planday_summarise_staff_cost는 부서, 직원, 직원 그룹, 교대 유형, 일, 주, 비용 출처 또는 파견 대 자체 직원별로 그룹화하여 약 12개 행을 반환합니다. 대용량 추출은 인라인이 아닌 파일 경로로 남습니다.

쓰기 안전

125개 작업 중 62개는 데이터를 수정합니다. 여기에는 교대 및 부서 삭제, 직원 출퇴근 기록이 포함됩니다. 이러한 작업은 검색은 가능하지만 게이트가 적용됩니다:

아무것도 숨겨지지 않습니다. 그러나 실제 근무표 포털을 대상으로 하는 LLM이 실수로 삭제 버튼을 얻지는 않습니다.

실사용 전환

위의 모든 작업에는 Planday 자격 증명이 필요하지 않습니다. 실데이터를 사용하려면:

1. Planday에서: Settings → Integrations → API Access → Create App로 이동합니다. SETUP.md에 나열된 범위를 선택하고 Authorise를 클릭한 다음 Client ID와 Refresh Token을 복사합니다. 가능한 한 적은 범위만 선택하세요. SECURITY.md를 참조하십시오.

2. .env에 PLANDAY_CLIENT_ID 및 PLANDAY_REFRESH_TOKEN으로 입력합니다.

3. pnpm doctor

pnpm doctor는 더 나아가 환경, 구성, 연결, 모든 Planday 범위를 개별적으로 확인한 다음 실제 보고서 빌드를 확인하므로 정확히 어떤 계층이 실패하는지 알 수 있습니다. 출력에는 자격 증명이나 직원 데이터가 포함되지 않으므로 공유해도 안전합니다. Planday는 각 영역을 별도로 관리하므로 완전히 유효한 토큰도 급여 영역에서 거부될 수 있습니다. 이 경우 보고서는 실패하는 대신 시간 및 비용, 그다음 비용 없는 근무 시간으로 단계적으로 축소됩니다.

코드 변경은 필요하지 않습니다. 샘플과 실사용은 동일한 코드 경로를 실행합니다.

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개 작업 각각을 호출하고 각 응답을 해당 작업의 스키마에 대해 검증합니다. 이것이 '전체 API 사용 가능'이라는 말을 주장이 아니라 검증된 사실로 만듭니다. 그리고 Planday가 엔드포인트를 추가하면 자동으로 포함되며, 업데이트해야 할 목록도 없습니다.

test/deploy.test.ts는 실제 서버리스 엔트리포인트를 esbuild로 번들링하고 라우트를 실행합니다. tsx에서는 통과하지만 번들링 후 깨지는 경우가 많기 때문입니다.

나머지 테스트는 수동으로 작성한 Power Query 병합을 깨뜨리는 사례에 대해 조인 규칙을 고정합니다: shift id가 없는 출퇴근 기록, 자정을 넘기는 교대, 시작 전 종료 쌍, 무급 휴게 시간 공제, 시간은 있지만 비용이 없는 월급제 직원, 배정되지 않은 열린 교대, 승인된 후 편집된 교대. 샘플 포털에는 일부러 이러한 사례가 모두 포함되어 있습니다.

맞춤 설정

파견 및 계약직 커버. Planday에는 파견 직원에 대한 일급 개념이 없으므로 직원 그룹 또는 교대 유형 이름에서 이를 추론합니다. 포털에서 다르게 태그한다면 src/timesheet/transform.ts의 AGENCY_RULE을 변경하세요. 정규식 하나입니다.

열 이름. src/timesheet/columns.ts가 단일 소스입니다. CSV 헤더, /columns 라우트, explain_columns MCP 도구, 생성된 powerquery/Timesheet.pq 모두 여기에서 파생되므로, 한 곳에서 열 이름을 바꾸면 모든 것이 업데이트됩니다. 그 후 pnpm gen을 실행하세요.

통화 및 로케일. Planday가 포털에 대해 보고하는 값을 사용합니다.

기타 Planday 데이터. 타임시트는 가장 잘 개발된 예시일 뿐입니다. 125개 작업 모두가 이미 planday_call과 /api/ 경로를 통해 접근할 수 있습니다 — 휴가 잔액, 매출, 급여율, 출퇴근 기록, 직원 이력 등. 타임시트와 같은 형태의 다른 보고서가 필요하다면 src/timesheet/이 복사할 패턴입니다.

보안

배포하기 전에 SECURITY.md를 읽으세요. 짧게 요약하면: 리프레시 토큰은 급여 데이터에 접근할 수 있고 자체적으로 만료되지 않으며, 어디에도 저장되지 않고, 쓰기는 기본적으로 거부되며, 취약점 신고를 위한 비공개 채널이 있습니다.

기여

이슈와 풀 리퀘스트를 환영합니다. Planday가 API를 변경하면: 스펙을 specs/에 다시 다운로드하고 pnpm gen을 실행하면 diff가 정확히 무엇이 변경되었는지 보여줄 것입니다.

AI 코딩 에이전트와 함께 작업하고 있나요? AGENTS.md는 바로 그 목적을 위해 작성되었습니다 — 재발견하는 데 비용이 많이 드는 도메인 지식과 쉽게 드러나지 않는 함정들을 담고 있습니다.