personio-mcp

Das fehlende Personio MCP

Hinweis: Dies ist ein Beta-Produkt und steht in keiner Verbindung zu Personio.

MCP-Server, der die öffentlichen APIs von Personio als Tools bereitstellt:

• Recruiting (v2): Jobs, Job-Kategorien, Kandidaten, Bewerbungen, Stufenübergänge

• Mitarbeiter (v1): Mitarbeiter auflisten/abrufen/erstellen/aktualisieren, Abwesenheitssalden, Attributkatalog, Profilbilder

• Zeiterfassung (v2): Anwesenheitszeiträume und Projekte (CRUD)

• Abwesenheiten (v1): Abwesenheitsarten, tagesbasierte Abwesenheiten, stundenbasierte Abwesenheitszeiträume

• Dokumente (v1): Dokumentkategorien, Dokument-Uploads

• Benutzerdefinierte Berichte (v1): Berichtsmetadaten, Berichtsdaten, Spaltenbeschriftungen

Die v1-Endpunkte für Anwesenheit/Projekte werden von Personio eingestellt (Sunset 2027-01-31), daher verwendet dieser Server deren v2-Nachfolger (/v2/attendance-periods, /v2/projects). Alle anderen Personal-Endpunkte folgen der offiziellen v1 Personnel Data API.

Basis-URL: https://api.personio.de

Anmeldedaten

1. OAuth2-Client – in Personio: Marketplace > Connected integrations > Create custom integration (erfordert den Core-Pro-Plan). Sie erhalten client_id / client_secret. Aktivieren Sie die benötigten Scopes/API-Ressourcen:

   • Recruiting: personio:recruiting:read (+ Schreibzugriff für einige Abläufe)

   • Personaldaten: Mitarbeiter lesen/schreiben, Abwesenheiten lesen/schreiben, Anwesenheit lesen/schreiben, Projekte lesen/schreiben, Dokumente lesen/schreiben, benutzerdefinierte Berichte lesen Beachten Sie die Unternehmens-ID der Integration – sie ist für alle Personal-Daten-Endpunkte erforderlich.

2. Recruiting-Token (nur für personio_create_application erforderlich) – statisches Token unter Settings > Integrations > API Credentials. Die Unternehmens-ID ist sichtbar unter https://{YOUR_COMPANY}.personio.de/configuration/api/credentials/management.

Related MCP server: Employee Management MCP Server

Umgebungsvariablen

Verwendung

Erfordert Node.js 20+. Direkt mit npx ausführen (keine Installation erforderlich):

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

Client-Konfiguration (z. B. 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

Die neue ChatGPT-Desktop-App unterstützt lokale STDIO-MCP-Server und teilt ihre MCP-Konfiguration mit Codex CLI und der IDE-Erweiterung (gespeichert in ~/.codex/config.toml).

Option A – über config.toml (empfohlen, da Sie damit Umgebungsvariablen festlegen können)

Fügen Sie dies zu ~/.codex/config.toml hinzu:

[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 = "..."

Starten Sie dann ChatGPT neu. Geben Sie /mcp im Composer ein, um zu überprüfen, ob der Server verbunden ist.

Option B – über die Benutzeroberfläche

1. Öffnen Sie Einstellungen und wählen Sie dann MCP-Server.

2. Wählen Sie Server hinzufügen.

3. Geben Sie einen Namen ein (z. B. personio), wählen Sie STDIO und setzen Sie den Befehl auf npx -y personio-mcp@latest.

4. Speichern und dann Neu starten wählen.

Hinweis: Wenn Sie über die Benutzeroberfläche vorgehen, setzen Sie die Anmeldedaten in Ihrer Shell-Umgebung, damit der Server sie beim Start lesen kann – oder bevorzugen Sie Option A, die die Anmeldedaten auf den Servereintrag beschränkt.

Tools

Gesundheit & Recruiting:

• personio_health_check – überprüft, ob die Anmeldedaten funktionieren

• 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 – übermittelt eine Bewerbung (v1); erfordert die zusätzlichen Umgebungsvariablen oben

Mitarbeiter:

• personio_list_employees – offset-paginiert; filtern nach E-Mail / updated_since / attributes[]

• personio_get_employee, personio_create_employee, personio_update_employee

• personio_get_employee_absence_balance

• personio_list_employee_attributes – Attributkatalog inkl. benutzerdefinierter (dynamischer) Felder

• personio_get_profile_picture – gibt Bildinhalt zurück; optionale Breite

Zeiterfassung:

• personio_list_attendance_periods – cursor-paginiert; umfangreiche Filter (Person, Projekt, Daten, 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

Abwesenheiten:

• personio_list_time_off_types – enthält Einheit (Tag/Stunde) und Genehmigungsanforderungen

• personio_list_time_offs, personio_create_time_off, personio_get_time_off, personio_delete_time_off – tagesbasierte Abwesenheiten

• personio_list_absence_periods, personio_create_absence_period, personio_delete_absence_period – stundenbasierte Abwesenheiten

Dokumente:

• personio_list_document_categories

• personio_upload_document – Multipart-Upload; Text- oder Base64-Inhalt übergeben (max. 30 MB)

Benutzerdefinierte Berichte:

• personio_list_custom_reports, personio_get_custom_report, personio_list_report_columns

Hinweise zur Personio-API:

• v2-Endpunkte (Recruiting, Anwesenheitszeiträume, Projekte) sind cursor-paginiert; Tools geben pagination.next_cursor zurück.

• v1-Personal-Endpunkte sind offset-paginiert; Tools geben pagination.total_elements / pagination.next_offset zurück.

• Mitarbeiter/Bewerbungen legen über v2 keine benutzerdefinierten Attribute oder Tags offen.

• E-Mail-Adressen von Mitarbeitern können nach der Erstellung nicht geändert werden.

• Die Erstellung von Bewerbungen funktioniert nur für aktuell veröffentlichte Positionen und ist auf ~100 Bewerbungen/min pro IP begrenzt.

• Dokument-Uploads sind auf ~60 Anfragen/min begrenzt.