HR WORKS MCP Server — Personalverwaltung & Lohn für KI-Agenten

HR WORKS für KI-Agenten

HR WORKS (vormals HRworks) ist die SaaS-HR-/Lohnplattform aus Freiburg, eingesetzt von ~20.000 KMU im DACH-Raum. Die v2 REST API legt den vollen operativen Datenbestand offen — Mitarbeiter, Abwesenheiten, Krankheiten, Arbeitszeiten, Homeoffice, Projekte, Bewerber, Organisationseinheiten, Feiertage, Kostenstellen — und AnythingMCP packt alles in einen drop-in MCP-Adapter mit 31 vorgefertigten Tools.

Warum ein MCP-Adapter für HR WORKS

HR WORKS bietet keinen langlebigen API-Key. Stattdessen wird {accessKey, secretAccessKey} an /v2/authentication gepostet und ein 15-minütiger JWT zurückgegeben, der dann als Authorization: Bearer <token> auf jeden weiteren Aufruf gesetzt wird. Diese kurze Token-Lebensdauer in Kombination mit per-Tenant-Rate-Limits und dem Dual-Identifier-Muster (Personalnummer oder Username auf den meisten Endpunkten) bringt fast jede DIY-Integration zum Stolpern.

Der AnythingMCP-Adapter erledigt:

• Den Bearer-Token-Vertrag (du liefern den Token, der Adapter sendet ihn auf jedem Aufruf)
• Sowohl Produktion als auch die api.demo-hrworks.de-Sandbox über HRWORKS_BASE_URL
• Die optionalen personIdentifierType-/usePersonnelNumbers-Parameter, wo zutreffend
• Die 1-Jahres-Maximalintervall-Regel auf Listing-Endpunkten
• Einen Live-Integrationstest, der beweist, dass der Bearer-Header wirklich injiziert wird (InvalidBearerTokenError statt MissingAuthorizationHeaderError)

Schnelleinrichtung

Schritt 1: AnythingMCP deployen

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Schritt 2: JWT aus HR WORKS holen

In der HR-WORKS-Verwaltung: Einstellungen → API → Access Key erzeugen für accessKey + secretAccessKey. Dann Token tauschen:

curl -X POST https://api.hrworks.de/v2/authentication \
  -H 'Content-Type: application/json' \
  -d '{"accessKey":"YOUR_ACCESS_KEY","secretAccessKey":"YOUR_SECRET_ACCESS_KEY"}'

Antwort: {"token": "eyJ..."}. Token-Lebensdauer ~15 Minuten — für Kurz-Workflows reicht der gleiche Token; für lang laufende Agenten diesen Adapter in einen Proxy mit automatischem Refresh wickeln.

Schritt 3: Adapter importieren

http://localhost:3000/connectors/store öffnen, HR WORKS importieren und JWT in HRWORKS_TOKEN einfügen.

Für Sandbox zusätzlich HRWORKS_BASE_URL=https://api.demo-hrworks.de setzen und Sandbox-Credentials nutzen.

Schritt 4: KI-Agent verbinden

{
  "mcpServers": {
    "hrworks": {
      "url": "http://localhost:4000/mcp"
    }
  }
}

Verfügbare Tools (31)

Konnektivität & Konfiguration

Personen

Abwesenheiten & Zeit

Projekte & Recruiting

(zeigt 30 von 31 Tools — installiere den Connector, um alle zu sehen)

KI-Agent Anwendungsfälle

• „Wer ist nächste Woche im Engineering im Urlaub?" — Manager-Selfservice für Abwesenheiten
• „Wie viele Krankheitstage hatte das Lager in Q1?" — HR-Analytik
• „Zeige Arbeitszeit-Summen für Jane Doe im März 2026" — Überstunden / Lohn-Vorbereitung
• „Liste aktive Bewerber für die Berliner Frontend-Stelle" — Recruiter-Handoff
• „Welche Mitarbeiter waren heute im Freiburger Büro anwesend?" — Facility-/Sicherheits-Sicht

Identifier-Konventionen

Die meisten personenbezogenen Endpunkte akzeptieren entweder die HR-WORKS-Personalnummer oder den Username. Nutze die optionalen personIdentifierType-/usePersonnelNumbers-Parameter, wenn der vorhandene Identifier nicht der Default ist — der Adapter reicht sie durch.

Datumsintervalle: 1-Jahres-Maximum

hrworks_list_absences, hrworks_list_sick_leaves, hrworks_list_remote_work und hrworks_list_working_times benötigen ISO beginDate/endDate (YYYY-MM-DD). Die HR-WORKS-API begrenzt die Spanne auf 1 Jahr (oder 31 Tage bei interval=days). Für längere Zeiträume jahresweise paginieren und client-seitig aggregieren.

Token-Refresh — bekannte Limitierung

Dieser Adapter sendet einen einzigen statischen Bearer-Token. Wenn der JWT abläuft (~15 Min), antwortet die API mit 401 und du musst einen frischen Token re-importieren. Für lang laufende Workflows einen Cron einrichten, der per /v2/authentication einen neuen Token holt und die HRWORKS_TOKEN-Env-Var des Connectors über die AnythingMCP-Admin-API aktualisiert.

Nächste Schritte

• HR WORKS mit Claude verbinden
• HR WORKS mit ChatGPT verbinden
• Personio MCP Guide — alternative DACH-HR-Anbindung
• Kenjo HR MCP Guide — alternative DACH-HR-Anbindung