mcp-server-personio

MCP server for the Personio HR API with two profiles and per-user scoping.

Profiles

One image, selected by PERSONIO_PROFILE:

• employee — self-service, hard-scoped to the requesting user: personio_get_my_profile, personio_get_my_absences (+ balances), personio_request_absence, personio_get_my_attendances, personio_record_attendance (WORK/BREAK periods, project tagging), personio_get_my_documents (incl. e-signature status + download), personio_list_absence_types, personio_list_projects, personio_whoami. The gateway forwards the verified user email (X-MCP-User, honored when PERSONIO_TRUST_FORWARDED_USER=true); the server resolves it to a person id and pins every call to it — Personio has no on-behalf-of mechanism, so this scoping is enforced here. Unknown emails fail closed.

• hr — the HR workbench: persons + employments (list/get/update), absences and attendances for anyone (list/create/delete), projects (full CRUD + members), compensation entries/types/jobs/salary bands (read-only — API-created compensation can never be corrected, so creation is deliberately not exposed), documents (list/download/upload), org data (legal entities, departments, teams, cost centers, workplaces), custom reports, recruiting reads (applications/candidates/jobs/categories), and an attribute-whitelist diagnostic. Write tools additionally require PERSONIO_ENABLE_WRITES=true.

Related MCP server: MCP Employee Identity Server

Guarantees

• skip_approval is never sent — absence/attendance writes always enter Personio's normal approval workflow (the v2 default; v1's silent-bypass default is one reason this server is v2-first).

• No delete-person tool. Employee-profile tools never accept foreign person ids.

• Legal-entity scope (PERSONIO_HR_LEGAL_ENTITY=<id>, HR profile): every person-addressed tool is confined to employees of that entity. Tools addressed by another id resolve the owning person first and fail closed when it cannot be determined: absence/attendance periods are fetched to read their person, balanceForEmail is resolved to a person, personio_upload_document's v1 employeeId is mapped to a person via its email, project membership changes check personId, and personio_manage_document requires ownerId (verified against the owner-filtered document list) on a scoped instance.

• Email lookups require exactly one person whose email matches case-insensitively; ambiguous or non-matching results fail closed.

• Caller-supplied ids used in URL paths are rejected if empty, ./.., or contain /, \, ?, # or their percent-encoded forms.

• HTTP transport: MCP_HTTP_TOKEN is compared in constant time. With PERSONIO_TRUST_FORWARDED_USER=true the HTTP server refuses to start unless MCP_HTTP_TOKEN is set, since the forwarded X-MCP-User header would otherwise be accepted from any caller.

• Only credential-whitelisted attributes are returned by Personio — personio_list_attributes shows what your credential can see (missing attributes are omitted silently, not errored).

Not possible via Personio's public API

Performance, surveys, whistleblowing, onboarding checklists, workflow automations (beyond outbound webhooks), e-signature initiation, and approving pending absence requests have no public API — those remain in the Personio UI.

Auth

One client_id/client_secret pair (Settings → Integrations → API credentials) drives both API generations: OAuth2 client-credentials against /v2/auth/token (form-encoded) for v2, and the stable 24h papi- token from /v1/auth for the two v1-only flows (absence balances, document upload).

Run

npm install
npm run dev          # stdio
npm run dev:http     # streamable HTTP on :3000/mcp (stateless)
npm test

Docker images: ghcr.io/borgels/mcp-server-personio (published on push to main).