personio-mcp

The missing Personio MCP

Note: This is a beta product and is not affiliated with Personio in any way.

MCP server exposing Personio's public APIs as tools:

• Recruiting (v2): jobs, job categories, candidates, applications, stage transitions

• Employees (v1): list/get/create/update employees, absence balances, attribute catalog, profile pictures

• Time tracking (v2): attendance periods and projects (CRUD)

• Absences (v1): time-off types, day-based time-offs, hour-based absence periods

• Documents (v1): document categories, document uploads

• Custom reports (v1): report metadata, report data, column labels

The v1 attendance/project endpoints are deprecated by Personio (sunset 2027-01-31), so this server uses their v2 successors (/v2/attendance-periods, /v2/projects). All other personnel endpoints follow the official v1 Personnel Data API.

Base URL: https://api.personio.de

Credentials

1. OAuth2 client — in Personio: Marketplace > Connected integrations > Create custom integration (requires Core Pro plan). Gives you client_id / client_secret. Enable the scopes/API resources you need:

   • Recruiting: personio:recruiting:read (+ write for some flows)

   • Personnel data: employee read/write, absence read/write, attendance read/write, project read/write, document read/write, custom report read Note the integration's company ID — it is required for all personnel-data endpoints.

2. Recruiting token (only needed for personio_create_application) — static token under Settings > Integrations > API Credentials. The company ID is visible at https://{YOUR_COMPANY}.personio.de/configuration/api/credentials/management.

Related MCP server: Employee Management MCP Server

Environment variables

Usage

Requires Node.js 20+. Run directly with npx (no install needed):

PERSONIO_CLIENT_ID=... PERSONIO_CLIENT_SECRET=... PERSONIO_COMPANY_ID=... npx -y personio-mcp@latest

Client config (e.g. Claude Desktop / opencode)

{
  "mcpServers": {
    "personio": {
      "command": "npx",
      "args": ["-y", "personio-mcp@latest"],
      "env": {
        "PERSONIO_CLIENT_ID": "...",
        "PERSONIO_CLIENT_SECRET": "...",
        "PERSONIO_COMPANY_ID": "..."
      }
    }
  }
}

ChatGPT desktop app

The new ChatGPT desktop app supports local STDIO MCP servers and shares its MCP configuration with Codex CLI and the IDE extension (stored in ~/.codex/config.toml).

Option A — via config.toml (recommended, since it lets you set env vars)

Add this to ~/.codex/config.toml:

[mcp_servers.personio]
command = "npx"
args = ["-y", "personio-mcp@latest"]

[mcp_servers.personio.env]
PERSONIO_CLIENT_ID = "..."
PERSONIO_CLIENT_SECRET = "..."
PERSONIO_COMPANY_ID = "..."
# Only needed for personio_create_application:
# PERSONIO_RECRUITING_TOKEN = "..."

Then restart ChatGPT. Type /mcp in the composer to verify the server connected.

Option B — via the UI

1. Open Settings, then select MCP servers.

2. Select Add server.

3. Enter a name (e.g. personio), choose STDIO, and set the command to npx -y personio-mcp@latest.

4. Save, then select Restart.

Note: if you go through the UI, set the credentials in your shell environment so the server can read them at startup — or prefer Option A, which keeps credentials scoped to the server entry.

Tools

Health & recruiting:

• personio_health_check — verifies credentials work

• personio_list_jobs, personio_get_job

• personio_list_job_categories, personio_get_job_category

• personio_list_candidates, personio_get_candidate

• personio_list_applications, personio_get_application, personio_list_application_stage_transitions

• personio_create_application — submits an application (v1); requires the extra env vars above

Employees:

• personio_list_employees — offset-paginated; filter by email / updated_since / attributes[]

• personio_get_employee, personio_create_employee, personio_update_employee

• personio_get_employee_absence_balance

• personio_list_employee_attributes — attribute catalog incl. custom (dynamic) fields

• personio_get_profile_picture — returns image content; optional width

Time tracking:

• personio_list_attendance_periods — cursor-paginated; rich filters (person, project, dates, status)

• personio_get_attendance_period, personio_create_attendance_period, personio_update_attendance_period, personio_delete_attendance_period

• personio_list_projects, personio_get_project, personio_create_project, personio_update_project, personio_delete_project

Absences:

• personio_list_time_off_types — includes unit (day/hour) and approval requirements

• personio_list_time_offs, personio_create_time_off, personio_get_time_off, personio_delete_time_off — day-based absences

• personio_list_absence_periods, personio_create_absence_period, personio_delete_absence_period — hour-based absences

Documents:

• personio_list_document_categories

• personio_upload_document — multipart upload; pass text or base64 content (max 30MB)

Custom reports:

• personio_list_custom_reports, personio_get_custom_report, personio_list_report_columns

Notes from the Personio API:

• v2 endpoints (recruiting, attendance periods, projects) are cursor-paginated; tools return pagination.next_cursor.

• v1 personnel endpoints are offset-paginated; tools return pagination.total_elements / pagination.next_offset.

• Employees/applications don't expose custom attributes or tags via v2.

• Employee emails cannot be changed after creation.

• Application creation only works for currently published positions and is rate limited to ~100 applications/min per IP.

• Document uploads are limited to ~60 requests/min.