HR WORKS MCP Server — German HR & Payroll for AI Agents

HR WORKS for AI Agents

HR WORKS (formerly HRworks) is the SaaS HR/payroll platform from Freiburg used by ~20,000 small and mid-size companies across DACH. The v2 REST API exposes the full operational dataset — employees, absences, sick leaves, working times, remote work, projects, applicants, organization units, holidays, cost centers — and AnythingMCP wraps all of it in a single, drop-in MCP adapter with 31 pre-built tools.

Why an MCP Adapter for HR WORKS

HR WORKS does not expose a long-lived API key. Instead, you POST {accessKey, secretAccessKey} to /v2/authentication and receive a 15-minute JWT that is then sent as Authorization: Bearer <token> on every subsequent call. That short token lifetime, combined with the per-tenant rate limits and the dual-identifier pattern (personnel number or username on most endpoints), trips up almost every DIY integration.

The AnythingMCP adapter handles:

• The bearer-token contract (you supply the token; the adapter sends it on every call)
• Both production and the api.demo-hrworks.de sandbox via the HRWORKS_BASE_URL override
• The optional personIdentifierType / usePersonnelNumbers parameters where applicable
• The 1-year-max date-interval rule on listing endpoints
• A live integration test that proves the bearer header is actually injected (InvalidBearerTokenError instead of MissingAuthorizationHeaderError)

Quick Setup

Step 1: Deploy AnythingMCP

git clone https://github.com/HelpCode-ai/anythingmcp.git
cd anythingmcp && docker compose up -d

Step 2: Mint a JWT from HR WORKS

In the HR WORKS admin: Settings → API → Generate Access Key to get an accessKey + secretAccessKey pair. Then exchange them for a JWT:

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

The response contains {"token": "eyJ..."}. Token lifetime is ~15 minutes — for short-lived workflows the same token is fine; for long-running agents wrap this adapter in a proxy that refreshes automatically.

Step 3: Import the Adapter

Open http://localhost:3000/connectors/store, click Import on HR WORKS, and paste the JWT into HRWORKS_TOKEN.

For the sandbox: also set HRWORKS_BASE_URL=https://api.demo-hrworks.de and use sandbox-issued credentials.

Step 4: Connect to Your AI Agent

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

Available Tools (31)

Connectivity & Configuration

| Tool | What it returns | |------|-----------------| | hrworks_health_check | API reachability — no auth required | | hrworks_list_organization_units | All active org units (uuid, number, name) | | hrworks_get_organization_unit | Full org-unit record | | hrworks_list_permanent_establishments | Permanent establishments (Betriebsstätten) | | hrworks_list_holidays | Public holidays per region/year | | hrworks_list_cost_centers | Cost centers configured for the tenant |

People

| Tool | What it returns | |------|-----------------| | hrworks_list_persons | Employee directory with filters | | hrworks_get_person | Full employee record | | hrworks_list_persons_master_data | Master data (HR-relevant attributes) | | hrworks_get_persons_today | Snapshot of who's active today | | hrworks_list_present_persons | Currently present (in-office/remote) people | | hrworks_get_leave_account | Leave account balance per person |

Absences & Time

| Tool | What it returns | |------|-----------------| | hrworks_list_absences | Absences over a date interval | | hrworks_list_absence_types | Configured absence types | | hrworks_list_vacation_types | Vacation type catalog | | hrworks_list_sick_leaves | Sick leaves over a date interval | | hrworks_list_sick_leave_types | Sick-leave categories | | hrworks_list_remote_work | Home-office / remote-work entries | | hrworks_list_working_times | Working-time entries (max 1y or 31d for interval=days) | | hrworks_list_time_recording_regulations | Time-recording rules in force |

Projects & Recruiting

| Tool | What it returns | |------|-----------------| | hrworks_list_projects | Projects with status | | hrworks_get_project | Full project record | | hrworks_list_project_customers | Customers attached to projects | | hrworks_list_job_applications | Open job applications | | hrworks_list_posts | Job postings | | hrworks_get_post | Full posting incl. description | | hrworks_list_applicants | Applicants in the pipeline | | hrworks_get_applicant | Full applicant record |

AI Agent Use Cases

• "Who is on vacation in the engineering team next week?" — manager-self-serve absence overview
• "How many sick days did the warehouse take in Q1?" — HR analytics
• "Show working-time totals for Jane Doe in March 2026" — overtime / payroll prep
• "List active applicants for the Berlin Frontend role" — recruiter handoff
• "Which employees were present in the Freiburg office today?" — facility/security view

Identifier Conventions

Most person-related endpoints accept either the HR WORKS personnel number or the username. Use the optional personIdentifierType / usePersonnelNumbers parameters when the identifier you have is not the default — the adapter will pass them through.

Date Intervals: 1-Year Maximum

hrworks_list_absences, hrworks_list_sick_leaves, hrworks_list_remote_work, and hrworks_list_working_times require ISO beginDate / endDate (YYYY-MM-DD). The HR WORKS API caps the span at 1 year (or 31 days if interval=days). For longer ranges, page through year-by-year and aggregate client-side.

Token Refresh — Known Limitation

This adapter sends a single static bearer token. When the JWT expires (~15 min), the API returns 401 and you must re-import a fresh token. For long-running workflows, run a cron that refreshes the token via /v2/authentication and updates the connector's HRWORKS_TOKEN env var via the AnythingMCP admin API.

Next Steps

• Connect HR WORKS to Claude
• Connect HR WORKS to ChatGPT
• Personio MCP Guide — alternative DACH HR connector
• Kenjo HR MCP Guide — alternative DACH HR connector