hibob-advanced-mcp

Ein MCP-Server für HiBobs Workforce Planning API – geplante Positionen, deren Vakanzen (Openings) und Budgets.

Dies ergänzt eine standardmäßige HiBob-HRIS-Integration, ersetzt sie aber nicht. Allgemeine HRIS-Funktionen (Personal, Abwesenheiten, Dokumente) gehören in die Hauptintegration; dieser Server stellt die Workforce-Planning-Oberfläche bereit, die in anderen HRIS-Systemen kein Äquivalent hat, sodass er nur für Kunden aktiviert werden kann, die ihren Personalbedarf in HiBob planen.

Er läuft über stdio, ist mit uvx installierbar und authentifiziert sich mit einem HiBob API-Servicebenutzer.

HiBob-Einrichtung

1. Gehen Sie in HiBob zu Einstellungen → Integrationen → API-Servicebenutzer und erstellen Sie einen Servicebenutzer. HiBob zeigt die Servicebenutzer-ID und das Token nur einmal an — kopieren Sie beide jetzt, da sie später nicht mehr abgerufen werden können.

2. Erstellen (oder wiederverwenden) Sie eine Berechtigungsgruppe, die diesen Servicebenutzer enthält, und erteilen Sie ihm:

   Funktionen → Workforce Planning → Positionsverwaltung → Positionen verwalten

   Servicebenutzer haben standardmäßig keine Berechtigungen. Ohne diese Freigabe gibt jeder Aufruf 403 zurück, und dieser Server wird Ihnen genau diese Berechtigung vorschlagen.

3. Wenn Ihr HiBob-Konto den API-Zugriff auf bestimmte IP-Adressen beschränkt, geben Sie die ausgehende IP-Adresse des Servers frei, auf dem dieser Server läuft.

Auch für reinen Lesezugriff ist dieselbe Berechtigung erforderlich – HiBob bietet keine schmalere Workforce-Planning-Berechtigung an. Verwenden Sie HIBOB_READ_ONLY=true (siehe unten), wenn der Server selbst keine Änderungen vornehmen soll.

Konfiguration

Standard-Proxyvariablen (HTTPS_PROXY, ALL_PROXY) werden berücksichtigt. Ein SOCKS5-Proxy benötigt das optionale Extra socks – siehe Installationszeile unten.

Ausführen

Auf einen Commit gepinnt, so sollte es deployt werden:

uvx --from 'git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>' hibob-advanced-mcp

Aus einem lokalen Checkout während der Entwicklung:

uvx --from . hibob-advanced-mcp --test

--test gibt die Version, die aufgelöste API-Basis-URL, ob Anmeldedaten gesetzt sind (niemals deren Werte), den Read-Only-Status und alle registrierten Tools aus und beendet sich dann. Damit lässt sich eine Installation verifizieren, ohne einen MCP-Client oder echte Anmeldedaten zu benötigen.

Mit einem SOCKS5-Proxy:

uvx --from 'git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>[socks]' hibob-advanced-mcp

Claude Desktop

{
  "mcpServers": {
    "hibob-workforce-planning": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>",
        "hibob-advanced-mcp"
      ],
      "env": {
        "HIBOB_SERVICE_USER_ID": "<service user ID>",
        "HIBOB_SERVICE_USER_TOKEN": "<service user token>"
      }
    }
  }
}

Einbindung in eine sandboxed MCP-Integration

Für einen Host, der MCP-Server als sandboxed Subprozesse mit der Claude-Desktop-Konfigurationsstruktur ausführt, lautet die Integrationskonfiguration:

{
  "server_type": "sandboxed",
  "sandbox_command": "uvx",
  "sandbox_args": [
    "--from",
    "git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>",
    "hibob-advanced-mcp"
  ],
  "sandbox_runtime": "python",
  "auth_type": "none",
  "sandbox_env": {
    "HIBOB_SERVICE_USER_ID": "<service user ID>",
    "HIBOB_SERVICE_USER_TOKEN": "$SECRET_KEY"
  }
}

Fügen Sie das Token des Servicebenutzers in das Feld für den geheimen Schlüssel der Integration ein: $SECRET_KEY wird innerhalb der Sandbox ersetzt, sodass das Token nie in der Konfiguration gespeichert wird. Die Serviceuser-ID ist kein Geheimnis und wird wörtlich eingefügt.

Kein --with 'mcp<2' erforderlich – dieses Paket pinnt das MCP-SDK selbst.

Laufender Betrieb

Auf einen Commit gepinnt, so sollte es deployed werden:

uvx --from 'git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>' hibob-advanced-mcp

Aus einem lokalen Checkout während der Entwicklung:

uvx --from . hibob-advanced-mcp --test

--test gibt die Version, die aufgelöste API-Basis-URL, ob Anmeldedaten gesetzt sind (nie deren Werte), den Read-only-Status und jedes registrierte Tool aus und beendet sich dann. Es verifiziert eine Installation ohne MCP-Client oder Live-API-Zugang.

Mit einem SOCKS5-Proxy:

uvx --from 'git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>[socks]' hibob-advanced-mcp

Claude Desktop

{
  "mcpServers": {
    "hibob-workforce-planning": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>",
        "hibob-advanced-mcp"
      ],
      "env": {
        "HIBOB_SERVICE_USER_ID": "<service user ID>",
        "HIBOB_SERVICE_USER_TOKEN": "<service user token>"
      }
    }
  }
}

Anbindung an eine sandboxed MCP-Integration

Für eine Integration, die MCP-Server als sandboxed Unterprozesse in der Claude-Desktop-Config-Form ausführt, lautet die Integrationskonfiguration:

{
  "server_type": "sandboxed",
  "sandbox_command": "uvx",
  "sandbox_args": [
    "--from",
    "git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>",
    "hibob-advanced-mcp"
  ],
  "sandbox_runtime": "python",
  "auth_type": "none",
  "sandbox_env": {
    "HIBOB_SERVICE_USER_ID": "<service user ID>",
    "HIBOB_SERVICE_USER_TOKEN": "$SECRET_KEY"
  }
}

Fügen Sie das Token des Servicebenutzers in das Schlüsselfeld der Integration ein: $SECRET_KEY wird dort ersetzt, sodass das Token nie selbst in der Konfiguration gespeichert wird. Die Serviceuser-ID ist kein Geheimnis und wird im Klartext eingetragen.

Ein Argument --with 'mcp<2' ist nicht nötig – dieses Paket pinnt das MCP-SDK selbst.

Tools

Feldwerte werden als flache Zuordnungen übergeben, zum Beispiel {"/position/fte": 100}. Das Präfix /position/ kann weggelassen werden ({"fte": 100}). Der Server verpackt Werte für Sie in HiBobs {"value": ...}-Envelope und entpackt Suchergebnisse wieder entsprechend.

Lesen

Suchergebnisse werden als {"count": N, "entries": [{"values": {...}, "display": {...}}]} zurückgegeben. values enthält die Rohwerte einschließlich der IDs, die die Schreib-Tools benötigen; display enthält HiBobs menschenlesbare Bezeichnungen. Die Openings- und Budgetsuchen sind cursorbasiert paginiert und geben has_more und next_cursor zurück; die Positionssuche ist nicht paginiert, daher sollten Sie nur die benötigten Felder anfordern und nach Möglichkeit filtern.

Schreiben (bei HIBOB_READ_ONLY weggelassen)

Schreibzugriffe sind auf zehn Aufrufe pro Minute begrenzt. Felder werden vor dem Senden validiert; bei ungültigen Werten wird ein Fehler zurückgegeben, ohne dass ein Request gesendet wird.

hibob_create_position erstellt eine Position zusammen mit ihrem ersten Opening und (optional) einem Budget in einem einzigen Aufruf.

Feld-Spickzettel

Erforderlich zum Erstellen einer Position:

Auf einer Position aktualisierbar: name, effectiveDate, managerPositionId, positionType, fte, employmentType, department, site, jobProfile, reason.

Filterbar: /position/status, /position/name, /position/hasOpenRequests, /position/id; /positionOpening/id, /positionOpening/status (vacant, starting, filled, departing), /positionOpening/positionOpeningName.

Felder wie department, site und jobProfile erwarten HiBob-Listenelement-IDs, keine Namen. Lösen Sie sie mit hibob_get_company_named_lists auf, bevor Sie eine Position erstellen oder aktualisieren.

Feld-Spickzettel

Erforderlich für das Anlegen einer Position:

Änderbar an einer Position: name, effectiveDate, managerPositionId, positionType, fte, employmentType, department, site, jobProfile, reason.

Filterbare Felder: /position/status, /position/name, /position/hasOpenRequests, /position/id; /positionOpening/id, /positionOpening/status (vacant, starting, filled, departing), /positionOpening/positionOpeningName.

Felder wie department, site und jobProfile erwarten HiBob-Listeneintrags-IDs, keine Namen. Lösen Sie sie mit hibob_get_company_named_lists auf, bevor Sie eine Position erstellen oder aktualisieren.

Entwicklung

uv venv
uv pip install -e '.[test,lint,typecheck]'
pytest

Linting, Formatierung und Typprüfung werden in CI erzwungen. Lokal:

ruff check .          # add --fix to apply the automatic fixes
ruff format .         # CI runs --check, so format before pushing
mypy                  # non-strict; paths come from pyproject.toml

Die Typprüfung ist bewusst nicht streng – untypisierter Code ist erlaubt, aber die Annotationen werden trotzdem geprüft, wo sie vorhanden sind.

Interaktive Erkundung der Tools:

npx @modelcontextprotocol/inspector uvx --from . hibob-advanced-mcp

Lizenz

MIT