hibob-advanced-mcp

An MCP server for HiBob's Workforce Planning API — planned positions, their openings, and their budgets.

This complements a standard HiBob HRIS integration rather than replacing it. Common HRIS functionality (people, time off, documents) belongs in the main integration; this server exposes the workforce planning surface that has no equivalent in other HRIS systems, so it can be enabled only for the customers who plan headcount in HiBob.

It runs over stdio, is installable with uvx, and authenticates with a HiBob API service user.

HiBob setup

1. In HiBob, go to Settings → Integrations → API service users and create a service user. HiBob shows the service user ID and token once — copy both now, as they cannot be retrieved later.

2. Create (or reuse) a permission group containing that service user, and grant it:

   Features → Workforce planning → Position management → Manage positions

   Service users have no permissions by default. Without this grant every call returns 403, and this server will tell you to add exactly this permission.

3. If your HiBob account restricts API access by IP address, allow the outbound IP of wherever this server runs.

Read-only use still needs the same grant — HiBob does not offer a narrower workforce planning permission. Use HIBOB_READ_ONLY=true (below) if you want the server itself to refuse to make changes.

Configuration

Standard proxy variables (HTTPS_PROXY, ALL_PROXY) are honoured. A SOCKS5 proxy needs the optional socks extra — see the install line below.

Running it

Pinned to a commit, which is how it should be deployed:

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

From a local checkout, during development:

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

--test prints the version, the resolved API base URL, whether credentials are set (never their values), the read-only state, and every registered tool, then exits. It verifies an install without needing an MCP client or live credentials.

With a 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>"
      }
    }
  }
}

Plugging into a sandboxed MCP integration

For a host that runs MCP servers as sandboxed subprocesses using the Claude Desktop config shape, the integration config is:

{
  "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"
  }
}

Paste the service user's token into the integration's secret key field: $SECRET_KEY is substituted with it inside the sandbox, so the token is never stored in the config itself. The service user ID is not a secret and goes in literally.

No --with 'mcp<2' argument is needed — this package pins the MCP SDK itself.

Tools

Field IDs are passed as flat mappings, for example {"/position/fte": 100}. The /position/ prefix may be omitted ({"fte": 100}). The server wraps values into HiBob's {"value": ...} envelope for you, and flattens search results back out.

Read

Search results come back as {"count": N, "entries": [{"values": {...}, "display": {...}}]}. values holds the raw values including the IDs the write tools need; display holds HiBob's human-readable labels. The opening and budget searches are cursor-paginated and return has_more and next_cursor; position search has no pagination, so request only the fields you need and filter where you can.

Write (omitted when HIBOB_READ_ONLY is set)

Writes are limited to ten calls a minute, so required fields are validated before a request is sent and write calls are never retried automatically. Read calls retry twice on 429 and 5xx responses, honouring Retry-After.

hibob_create_position creates one position per call, together with its first opening (HiBob requires one) and an optional budget.

Field cheat sheet

Required to create a position:

Updatable on a position: name, effectiveDate, managerPositionId, positionType, fte, employmentType, department, site, jobProfile, reason.

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

Fields such as department, site and jobProfile take HiBob list item IDs, not names. Resolve them with hibob_get_company_named_lists before creating or updating a position.

Development

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

Lint, formatting and types are enforced in CI:

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

Type checking is deliberately non-strict — annotations are checked where they exist, but untyped code is allowed. The package ships a py.typed marker, so its annotations are visible to anything that imports it.

Inspect the tools interactively:

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

License

MIT