Planday → Excel, Power BI y Claude

El Timesheet Report de Planday — el de las horas trabajadas y el coste de personal por turno — no tiene un único endpoint de API. La mayoría lo descubre por las malas, después de conectar Power Query a algo que no debía y recibir exactamente 50 filas.

Este proyecto resuelve ambos problemas:

1. Un traductor que compone el Timesheet Report real a partir de los tres endpoints que Planday nunca combina, y lo sirve a Excel o Power BI como una fuente en tiempo real.

2. Un servidor MCP que cubre la totalidad de la API de Planday — las 125 operaciones — para que puedas hacer preguntas en lenguaje natural: «¿cuánto nos costó la cobertura de agencia en julio, por departamento?»

Con licencia MIT. Se ejecuta en tu propia infraestructura. Tus credenciales de Planday nunca salen de ella.

Aún no probado contra un portal en producción. Todo esto funciona contra un portal de ejemplo realista y el cliente de la API se genera a partir de las especificaciones publicadas por el propio Planday, pero nadie lo ha apuntado todavía a datos reales. Si ese es tu caso, lee primero TESTING.md — explica cómo reconciliar con el informe propio de Planday y es honesto sobre dónde es más probable que falle. Hay un comando pnpm doctor que revisa cada capa y distingue un bug real de un problema de configuración.

¿Solo quieres que funcione?

→ SETUP.md es la guía paso a paso, pensada para quien gestiona el cuadrante más que para un desarrollador. Unos 20 minutos, sin programar y sin coste de ejecución.

Una vez desplegado, al abrirlo en un navegador verás esto: te dice qué está configurado, ejecuta una extracción de prueba real y te genera el fragmento de Power Query con tu propia URL ya incluida:

El resto de este archivo es para desarrolladores.

Requisitos: Node 20 o superior, y nada más. pnpm coincide con el lockfile, pero npm install funciona igualmente.

Todo lo que hay a continuación funciona con datos de ejemplo realistas. No se necesitan credenciales de Planday para verlo funcionar: es la forma más rápida de decidir si hace lo que quieres.

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.

Las dos cosas que hacen tropezar a todo el mundo

1. No existe un endpoint del Timesheet Report

https://openapi.planday.com/api/absence y sus hermanas son páginas de documentación, no endpoints de API: un error fácil y muy común. Y Absence es la contabilidad de vacaciones y horas extra de Planday, nada que ver con los partes horarios.

El Timesheet Report es una combinación de tres endpoints:

Además, hr/departments, hr/employees, hr/employeegroups y scheduling/shifttypes para convertir los ids en nombres. Esa combinación está en src/timesheet/transform.ts.

2. El límite de 50 registros

Los endpoints de listado de Planday declaran limit con maximum: 50 en su propia especificación. Subirlo no hace nada: el servidor te ignora en silencio. La única forma de avanzar es iterar con offset hasta tener paging.total registros.

El detalle curioso y útil: los tres endpoints de informe anteriores no están paginados en absoluto. Son llamadas masivas por rango de fechas. Así que, una vez estás en los endpoints correctos, el problema de los 50 registros casi desaparece: solo afectaba a las pequeñas tablas de referencia.

También conviene saber

Cada petición a Planday necesita dos cabeceras, no una:

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

Si falta X-ClientId, obtienes un 401 idéntico al de un token inválido. Los tokens de acceso también caducan al cabo de una hora, así que cualquier tarea programada tiene que renovarlos; esta es la principal razón por la que hacer esto en Power Query puro es desagradable, y por la que existe el puente que se describe más abajo.

Related MCP server: TimeChimp MCP Server

Cómo llevarlo a Excel o Power BI

Dos opciones. Se adaptan a presupuestos distintos y ambas están incluidas.

Opción A — el servicio puente (recomendado)

Un pequeño servicio se sitúa entre Planday y Excel. Gestiona OAuth, la renovación horaria del token y toda la paginación, de modo que Power Query se convierte en una única llamada Web.Contents.

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

Abre http://localhost:8787 para ver una página de configuración: muestra qué hay configurado, ejecuta una extracción de prueba y te entrega un fragmento de Power Query con tu propia URL ya incluida.

El endpoint contiene salarios y sueldos, por lo que está autenticado desde el primer commit: el secreto compartido va en la cabecera x-bridge-key. Rechaza toda operación de escritura de forma categórica, sin importar la configuración: una URL que una hoja de cálculo pueda actualizar jamás debe poder modificar un cuadrante en producción.

Opción B — sin servidor en absoluto

powerquery/Timesheet-direct.pq habla directamente con Planday desde Power Query, incluido el bucle de offset con List.Generate que resuelve el problema de los 50 registros. Es más lento y se re-autentica en cada actualización, pero no cuesta nada ejecutarlo.

El servidor MCP

19 herramientas que cubren las 125 operaciones de Planday.

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

Para Claude Desktop, añade esto a 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"
      }
    }
  }
}

Deja fuera por completo las dos variables de Planday para ejecutarlo contra el portal de ejemplo.

Registrar 125 herramientas separadas saturaría a la mayoría de los clientes MCP y quemaría decenas de miles de tokens de contexto en descripciones antes de que se haga una sola pregunta. Por eso la superficie es total, pero el registro está por niveles:

Acceso universal — 3 herramientas, las 125 operaciones

• planday_search_operations — encuentra cualquier endpoint por palabra clave

• planday_describe_operation — su firma completa y la forma de la respuesta

• planday_call — invócalo, validado contra la especificación y con la paginación gestionada

Todo lo que Planday puede hacer es accesible desde aquí, incluidos endpoints en los que nadie ha pensado todavía.

Lecturas seleccionadas — 12 herramientas para el camino habitual: departamentos, empleados, grupos de empleados, tipos de turno, puestos, turnos, fichajes, registros de ausencia, nóminas, tiempo y coste, historial de planificación, además de planday_whoami.

Composiciones — 4 herramientas que hacen lo que la API por sí sola no puede hacer en una sola llamada: planday_get_timesheet (la combinación triple), planday_summarise_staff_cost, planday_export_timesheet_csv, planday_explain_columns.

Por qué puede responder preguntas en lugar de limitarse a devolver datos

Ocho semanas de un portal mediano superan con creces el millar de filas. Pasárselas a un modelo como JSON crudo agota su contexto e invita a errores aritméticos. Por eso la agregación ocurre en el servidor: planday_summarise_staff_cost agrupa por departamento, empleado, grupo de empleados, tipo de turno, día, semana, origen del coste o personal de agencia frente a propio, y devuelve una docena de filas. Las extracciones grandes se devuelven como una ruta de archivo, nunca incrustadas.

Seguridad de escritura

62 de las 125 operaciones modifican datos: incluyen borrar turnos y departamentos, y fichar a los empleados de entrada y salida. Estas son visibles pero restringidas:

Nada está oculto, pero un LLM apuntado a un portal real de planificación de turnos no consigue un botón de borrar por accidente.

Puesta en producción

No se necesitan credenciales de Planday para nada de lo anterior. Cuando quieras datos reales:

1. En Planday: Settings → Integrations → API Access → Create App. Marca los scopes indicados en SETUP.md, haz clic en Authorise y copia el Client ID y el Refresh Token. Marca los menos scopes que puedas permitirte: consulta SECURITY.md.

2. Ponlos en .env como PLANDAY_CLIENT_ID y PLANDAY_REFRESH_TOKEN.

3. pnpm doctor

pnpm doctor va más allá: comprueba el entorno, la configuración, la conexión, cada scope de Planday por separado y, a continuación, una construcción real del informe, así puedes ver exactamente qué capa está fallando. Su salida no contiene credenciales ni datos del personal y se puede compartir sin riesgo. Planday restringe cada área por separado, de modo que un token perfectamente válido puede ser rechazado en nóminas; cuando eso ocurre, el informe se degrada a tiempo y coste, y luego a horas sin coste, en lugar de fallar.

No hacen falta cambios de código. El portal de ejemplo y el real ejecutan el mismo código.

Planday ofrece una prueba gratuita de 30 días con acceso a la API, y facilita un portal de demostración para desarrolladores cuando se solicita; es útil para probar una integración sin tocar un cuadrante en producción.

Cómo se mantiene correcto

Todo el cliente está generado a partir de las especificaciones OpenAPI del propio Planday, que están incluidas en specs/. Los envoltorios de endpoints escritos a mano quedarían desincronizados en cuanto Planday publicara un cambio; los generados se regeneran en segundos.

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

La prueba de cobertura invoca cada una de las 125 operaciones y valida cada respuesta contra el esquema de esa operación. Eso es lo que convierte «toda la API está disponible» en un hecho verificado y no en una afirmación; y si Planday añade un endpoint, queda cubierto automáticamente, sin ninguna lista que haya que acordarse de actualizar.

test/deploy.test.ts empaqueta el entrypoint serverless real con esbuild y ejercita las rutas, porque muchas cosas funcionan bajo tsx y aun así se rompen al empaquetar.

El resto de pruebas fijan las reglas de la combinación contra los casos que rompen una combinación hecha a mano en Power Query: un fichaje sin id de turno, un turno que cruza la medianoche, un par con el fin antes del inicio, la deducción de pausa no pagada, un empleado con salario mensual que tiene horas pero sin coste, un turno abierto sin asignar y un turno editado después de haber sido validado. El portal de ejemplo los contiene todos a propósito.

Adaptarlo

Cobertura de agencia y contratas. Planday no tiene un concepto de primera clase para el personal de agencia, así que esto se infiere a partir del nombre del grupo de empleados o del tipo de turno. Si tu portal lo etiqueta de otra forma, cambia AGENCY_RULE en src/timesheet/transform.ts. Es una única expresión regular.

Nombres de columna. src/timesheet/columns.ts es la única fuente de verdad. La cabecera CSV, la ruta /columns, la herramienta MCP explain_columns y el powerquery/Timesheet.pq generado derivan todos de ella, así que renombrar una columna allí actualiza todo. Ejecuta pnpm gen después.

Moneda y configuración regional. Se toman de lo que Planday informe para tu portal.

Otros datos de Planday. La hoja de tiempos es solo el ejemplo mejor desarrollado. Cada una de las 125 operaciones ya es accesible mediante planday_call y la ruta /api/ — saldos de ausencias, ingresos, tarifas de pago, reloj de fichaje, historial de empleados. Si quieres otro informe con el mismo formato que la hoja de tiempos, src/timesheet/ es el patrón a copiar.

Seguridad

Lee SECURITY.md antes de desplegar esto. Versión breve: el token de actualización accede a los datos de nómina y no caduca por sí solo, no se almacena nada en ningún sitio, las operaciones de escritura se rechazan por defecto y existe un canal privado para notificar vulnerabilidades.

Contribuir

Las incidencias y las solicitudes de extracción son bienvenidas. Si Planday cambia su API: vuelve a descargar las especificaciones en specs/, ejecuta pnpm gen, y el diff te mostrará exactamente qué ha cambiado.

¿Estás trabajando en esto con un agente de codificación de IA? AGENTS.md está escrito para eso — contiene el conocimiento del dominio y las trampas no obvias que son costosas de redescubrir.