hibob-advanced-mcp

An MCP server for HiBob's Workforce Planning API, tasks, employee termination, time off, and Reports API.

This complements a standard HiBob HRIS integration. Common HRIS functionality (people, documents) belongs in the main integration; this server adds planned positions, openings, budgets, tasks, time off and access to saved reports.

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

   To use the tasks tools, also grant the service user access to the Tasks API (read, and complete for hibob_complete_task).

   To terminate employees with hibob_terminate_employee, grant People's data → People's fields → Edit on the Lifecycle category, plus View on employees' names and work emails so the employee can be looked up.

   Reading and changing employee data (hibob_get_employee, hibob_update_employee) needs People's data → People's fields: View on the categories read, Edit on those changed, and View history to read a table's earlier rows. HiBob skips fields the service user may not edit without saying so; the update tool reads every change back to catch that.

   Time off needs People's Data → Time off: See who's out today → See who's out to list requests (plus See who's out because of a private policy or policies with a custom name for private ones), Balance → See people's time off and sick leave balances for balances, and Requests → Create, edit and cancel people's requests that haven't been approved yet to read a request by ID, book and cancel (and to list pending requests). Policy types, and booking, also need Features → Time off → Settings → Manage company's time off settings. HiBob's label stops at requests not yet approved, yet the demo tenant's service user cancelled approved ones; check this on your own account if approved leave must be cancellable.

   Reports need Features → Reports → View reports according to people's data access rights, plus access to the employees and fields included in each report. Reports containing formulas also need Features → Formulas in Grids → View formulas in grids. Reports do not require the workforce planning permission.

   Service users have no permissions by default. The server identifies the relevant permission when an endpoint denies access.

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

Read-only workforce planning use still needs the same workforce planning grant. Use HIBOB_READ_ONLY=true (below) to omit employee/task/workforce mutation tools; report generation and downloads remain available.

Related MCP server: humaans-mcp

Configuration

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

Hiding people data

Finding a person by name still works with HIBOB_HIDE_PEOPLE_DATA on, so that hibob_get_employee and hibob_find_employee stay useful. What changes:

• hibob_get_employee reads only ID, display, full, first and last name, work email, work phone, work mobile and work site. With no fields named it returns the display name, email, phones and site. Any other field, such as job title, salary or a personal phone, is refused before HiBob is asked for it, and so is history.

• The job title is left out of the employee shown in every employee tool.

• hibob_update_employee and hibob_add_employee_record still write, but do not show what a change replaced (from) or what HiBob holds in place of a change it did not keep (read).

• hibob_list_employee_fields is unchanged: it describes fields and tables but holds no employee data.

• Of the time off tools only hibob_list_timeoff_policy_types is registered: the rest show who is off, sickness included.

Not covered: the workforce planning tools, tasks (hibob_list_open_tasks, hibob_get_employee_tasks) and reports. Reports can include any people field, so keep their separate HiBob permission off the service user if it must not reach that data. The lock limits what this server shows; the service user's HiBob permissions still decide what HiBob can return.

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; the budget search takes a limit up to 1000 (HiBob rejects anything larger), which is one page for most companies. Position search has no pagination and ignores limit entirely, so request only the fields you need and filter where you can.

Seven of the read tools do work HiBob's API cannot do in one request:

• hibob_get_openings_for_positions answers "which openings belong to this position?". HiBob's opening search only filters by an opening's own ID, status or name, never by its parent position. The tool sends a filter every opening satisfies (/positionOpening/id notEqual "1", the clause verified against HiBob's sandbox), pages through every opening 100 at a time, and joins on /positionOpening/positionId in memory. Pass several positions at once to pay for the scan once; a statuses filter is applied by HiBob and shortens it. Positions may be given by numeric ID or by name (P-0000000368); names are resolved in one search first and reported back in resolved_positions. The result reports counts_by_position, so a position with no openings shows as 0, and scan_complete, which is false only if the scan hit its 10,000-opening safety cap.

• hibob_get_positions_under answers "which positions report up to me, and which are filled?". Position search cannot filter by manager position or by holder, but it returns every position in one unpaginated response with its manager position and the employee filling it, so the tool fetches them all (one request) and walks the reporting tree in memory. The top position can be given as a position ID, a position name (P-...), the holder's HiBob employee ID, the holder's work email or the holder's name; those last two matter because HiBob has no call from an employee to their position, and a name fitting several people returns candidates instead. An email costs one narrowly scoped call to HiBob's people search that asks for the employee ID and nothing else; it is the only use of the people API by the position tools; hibob_find_employee also uses it, to turn an email into an employee ID for the tasks tools, and hibob_terminate_employee to find the employee it terminates. The result lists each position beneath with its status, holder and own manager position, depth levels down (1 for direct reports), with counts_by_status; a statuses filter is applied after the walk so a vacant position under a filled one is never lost.

• hibob_search_position_budgets names the position each budget belongs to. A budget record carries no reference to its position — HiBob's only link runs the other way, as /position/budget on the position — so a budget fetched on its own genuinely cannot be attributed to anything, and the honest reading of one in isolation is that its cost belongs to nobody. The tool therefore scans every position for that reference and reports the owner as each entry's position. It sits beside values rather than among the field IDs because it is synthesised here, and HiBob can neither filter nor sort on it. null means no position references that budget; a failed lookup returns the budgets with position_link_error and no position key at all, which is deliberately not the same as null. Pass include_position: false for a pure total to skip the extra request.

• hibob_get_position_costs answers "what does this position cost?". Cost is not a field on a position. /objects/position/search exposes 38 fields and none of them are cost; the figures the HiBob UI shows on a position (expected base salary, total position cost, total converted cost, prorated cost) live on a separate positionBudget object. The only link is /position/budget on the position, an entity_reference holding the budget's ID — a budget carries no position ID of its own, so the join only exists in that one direction. The tool fetches the named positions, reads that reference off each, fetches exactly those budgets and merges them, in two requests; positions may be given by numeric ID or by name (P-0000000368), and names cost one more search, reported back in resolved_positions. Positions whose budget is missing are listed in positions_without_budget rather than dropped.

  Two HiBob behaviours make this hard to discover, and both fail silently. Unrecognised field IDs are dropped without an error — asking the position search for /positionBudget/totalPositionCostCurrencyValue, or for an entirely invented field, returns 200 OK with the key simply absent, so a request for cost looks like it worked and came back empty. And filtering is whitelisted: positions filter only on /position/status, /position/name, /position/hasOpenRequests and /position/id, budgets only on /positionBudget/id and /positionBudget/proRatedCostPercentage. Anything else is a 400, so no cost figure can be filtered or grouped by HiBob at all.

• hibob_summarize_position_costs rolls that cost up across the company, or a department, or everything still vacant — the thing HiBob cannot do itself, since cost is neither filterable nor groupable. It fetches every position and every budget (two requests), joins them and aggregates here, optionally grouped by department, site, status, jobProfile or currency and restricted to given statuses. Only the converted figures are summed: HiBob reports each position's total in its own local currency, and a company can have many, so adding those together would produce a meaningless number, while the converted values share the company's reporting currency. If converted costs ever arrive in more than one currency, total_converted_cost is null and totals_by_currency carries a total per currency instead of one wrong number.

• hibob_resolve_list_values turns the option names a user chose back into the IDs HiBob wants. A form is offered by option name, and what comes back from it is the name; by then a bot may have lost the form response that paired names with IDs, and the ID of the list behind the field with it. The tool takes what is left, the field as an ID or its label (Locations for hiring, Site) and the names, finds the list from the field's metadata, fetches that one list, and matches each name exactly, ignoring case, against the items and, for a tree-shaped list, their path labels (Spain > Madrid - Office). It returns values, the IDs in the order given and ready to submit, and says whether the field is multi. A name matching nothing comes back under unmatched with the nearest items as candidates; one that two items share comes back under ambiguous rather than guessed at; a branch of a tree, which cannot be submitted, offers its leaves. Every list field on a form names this tool as resolve_with.

• hibob_get_workforce_form returns everything needed to fill in a create form as one blob: for position (the default) that is the position's fields plus the nested opening (required) and budget (optional) sections; for positionOpening or positionBudget just that object. Every list-backed field (department, site, job profile, currency, ...) arrives with its options resolved from the company's named lists, including the id to submit (a list longer than max_options, 100 by default, is truncated, and the field then says to fetch the rest with hibob_get_company_named_lists); fields with a fixed vocabulary (position type, recruitment status, pay periods) carry allowed_values; each field says whether it is required, and fields HiBob sets itself are listed separately as read_only_fields. Each section names the write tool argument it maps to (position_fields, opening_fields, budget_fields or fields), so the filled-in form can be passed straight to the create tool.

  A form has to be complete when it is generated (a Slack form, say, needs every option up front), and job profiles and manager positions run to a thousand items. So for a position form the tool takes what the user should be asked first: department, job_profile (a rough title) and manager (a name, P-... position name or ID). A department pre-fills its field and narrows the manager choices to that department's branch of the position tree and the job profiles to those naming the department; a title or a manager's name picks out the matching leaves, and a single match pre-fills the field as value. Tree-shaped lists are offered as their leaves, labelled by path (Data > Head of Data > P-0001 · London · Jane Doe). If any of these three fields still cannot be offered within max_options, the response carries questions (each with the argument to pass, a question to ask the user and, when few enough, candidates) instead of sections; answer them and call again.

Write (omitted when HIBOB_READ_ONLY is set)

Every tool that takes a position or an opening accepts it either as its numeric ID or as the name HiBob shows: P-0000000368 for a position, O-6853240227 for an opening. A name costs one search before the write, which comes out of the search limit rather than the write limit; a name that matches nothing, or that HiBob has let two records share, is refused rather than guessed at. Openings are always looked up before an update or delete, whether given by ID or by name, because the lookup returns the position each opening belongs to. A write addressed under the wrong position, such as O-6853240227 beneath the ID of another position, is refused before anything is sent. Budgets have no name and need none: a position carries its budget's ID as /position/budget, so hibob_update_position_budget finds the budget from the position, and its budget_id argument is optional. If a budget_id is given it must be that position's budget, so an ID carried over from another position is refused; a second budget for a position that already has one is refused likewise. Each result reports the numeric position_id (and opening_id or budget_id) actually written to.

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. Named lists and metadata are each limited to fifty calls a minute and a position form needs a dozen lists and three metadata calls, so both are cached in the server process for five minutes, shared between the form, named-list and resolve tools; a failed fetch is not cached. Every create and update reads the record back through its search endpoint and returns it with verified; a read-back failure is reported as verification_error rather than as a failed write, and a created opening is checked to belong to the position it was created under.

hibob_create_position creates one position per call, together with its first opening (HiBob requires one) and an optional budget. HiBob's API cannot give a new position a budget end date, so a role that ends takes cancellation_date instead: once the position is created, its cancellation is scheduled for that day (a second write call, and the same endpoint as hibob_schedule_position_cancellation). The date must fall after the budget date and the opening's expected start date, and is checked before anything is sent; /position/endEffectiveDate in position_fields is refused with a pointer to it. If the scheduling fails after the create, the result still carries the new IDs, with verified: false and HiBob's reason.

hibob_cancel_position cancels a position now; HiBob refuses it for a filled position. hibob_schedule_position_cancellation cancels one on a later date instead, such as when a fixed-term role ends: until then the position shows as "Cancelled soon", and at midnight on the date HiBob cancels it and unassigns whoever holds it. HiBob's API documents no way to undo a scheduled cancellation, so the tool looks the position up first and refuses, before anything is sent, a position already cancelled or cancelled soon, a date that is not a real day today or later, and a filled, starting or departing position unless unassign_holder is true, the error naming the holder so the user can be asked. The position is read back afterwards with its status and budget end date.

hibob_terminate_employee adds a termination entry to an employee's lifecycle; HiBob changes their status to Terminated on the termination date. HiBob's API documents no way to undo a termination, so everything is checked before the one request is sent. The employee may be given by employee ID or work email and must match exactly one active employee, whose name the result reports. termination_reason and reason_type may be given by name (Resigned) or ID, and are matched exactly, ignoring case, against the company's terminationreason and lifecycleReasonType lists (HiBob's list names are case-sensitive); a name matching nothing, or several items, is refused with the closest items. last_day_of_work may not fall after termination_date, and a notice period needs both its length and its unit (days, weeks, month or years, as HiBob spells them). The tool does not revoke the employee's access to Bob, and nothing is read back afterwards: the result reports exactly what HiBob accepted.

hibob_update_employee takes changes as field labels or IDs mapped to values given by name, and works out where each goes: plain fields in one PUT /people/{id}, the work email and start date through their own endpoints. List values and people (by name, email or ID) are matched exactly, ignoring case; anything unmatched or ambiguous, and an amount without a currency, comes back as {"status": "needs_input", "questions": [...]} with candidates and nothing written. Fields HiBob keeps a dated history of need an effective_date: job title, department, site, manager ("Manager" and "Reports to" are the same column; give only one), change type (Promotion, Lateral Move, ...: without it HiBob tags the new row "Other"); employment contract, type, pay type, FLSA code and holiday calendar; salary amount, pay period and frequency; home address (lines 1 and 2, city, post code, state or region, country). Without one the tool asks for it and never assumes today. Each such change adds a new row to HiBob's work, employment, salary or address table. HiBob replaces a row wholesale (a column left out is stored empty), so the new row copies every column of the row in force before its date and lays the change over it. Nothing is written if HiBob hides part of the table from the service user, the employee already has a row on that date (existing rows are never edited), or there is no earlier row to copy (a first salary row is an exception: it needs the amount with its currency, the pay period and the pay frequency; a first address row is another: it is just what you give). A later row that still holds a different value comes back as a question; allow_later_rows: true goes ahead. A bare salary amount takes its currency from the row it copies, and a change that matches the row it would copy adds nothing. New rows carry HiBob's default change type; a reason is recorded on work, employment and address rows (the salary table has no reason column). Every new row is read back and compared column by column, and anything HiBob dropped is listed under unconfirmed. Working patterns cannot be changed yet, and the derived columns (FTE, weekly hours) are copied as they were. Fields HiBob derives (tenure, job architecture fields that follow the job profile, people analytics, lifecycle) are refused as not writable, and hibob_list_employee_fields says which. An effective_date other than today is refused for plain fields, which HiBob changes immediately. Writes go plain fields, start date, then email, each once; a failure stops the rest (partial). HiBob skips fields the service user may not edit without saying so (a live check saw a 200 for a request whose fifth field was not stored), so every change is read back, re-reading for about 10 seconds, and anything still not visible is listed under unconfirmed.

hibob_add_employee_record adds one row to the tables HiBob keeps several rows in: variable pay, entitlements and deductions (dated: the tool asks for the effective date), equity grants, training, bank accounts, dependents, right-to-work documents, and the company's custom tables. A new record copies nothing, so the columns it needs are asked for, with the options a list offers; a value matching nothing or several things comes back as a question; the type's list, column and date rules are in hibob_list_employee_fields under record_types. Entitlement and deduction types are sent by name, as HiBob wants. Calling again with the same values adds nothing (the identical record is reported), so a retry after a lost response is safe. Bank account, IBAN, routing and document numbers are sent in full and shown back masked to their last four characters, including in hibob_get_employee's history. Every record is read back and compared; a dropped column is listed under unconfirmed, and a dropped required column is called out (HiBob stores nothing for a currency it cannot read, such as a made-up code, yet still passes the mandatory check). HiBob's API has no way to edit or delete a record through this server. Bank accounts and right-to-work records need the sensitive-data write permission in HiBob.

Time off

The time off tools take an employee by ID, work email or name, and requests by HiBob's numeric request ID (requestId in hibob_list_timeoff_requests).

HiBob uses two vocabularies for a request's state. Who's out lists only live requests, as approved or pending; reading one request gives pending_approval, approved or canceled. A cancelled request drops out of who's out, so hibob_get_timeoff_changes is how to find one. HiBob's API cannot approve or decline a request.

hibob_cancel_timeoff_request works around a HiBob behaviour found live: DELETE /timeoff/employees/{id}/requests/{requestId} cancels by request ID alone and ignores the employee in the path, so it cancels anyone's request. A GET of the same path does check, answering 404 for another employee's request, so the tool reads the request under the employee first and sends nothing unless it is theirs. It then:

• reports a request already canceled without sending anything (HiBob would answer 200 and change nothing);

• refuses any state other than pending_approval or approved;

• refuses a request that started before today unless cancel_started is true. HiBob would cancel it, past or in progress, pending or approved, but the whole request goes, days already passed included;

• sends the DELETE once and reads the request back to confirm canceled. HiBob cancels at once, with no approval step for the cancellation.

hibob_submit_timeoff_request books whole and half days (afternoon to start at midday, morning to finish at midday; the same portion at both ends for a single half day). HiBob checks the request against the policy and its refusals are passed on in full, such as a conflict naming the request it overlaps, a request on non-working days only, or a missing reason code. skip_manager_approval approves the request at once. The new request is read back to report its status.

Reports

Configure a report and its filters in Bob, then call hibob_list_reports to find its numeric ID. The API returns only reports and data visible to the service user; a successful response does not prove the service user can see the entire workforce or every requested field.

For programmatic use, download JSON with machine-readable values:

{"report_id": 12345, "format": "json", "include_info": true}

Pass this to hibob_download_report. The result contains status: "ready", the parsed data, byte_count, and a SHA-256 checksum of the downloaded bytes. human_readable: "APPEND" includes labels alongside IDs; "REPLACE" replaces IDs with labels. This option is valid only for JSON. An optional locale selects the report's column language.

CSV is returned as text, preserving leading zeroes, duplicate column names, metadata rows and embedded newlines. XLSX is returned as data_base64 with encoding: "base64". The server does not write files or silently truncate reports. It enforces a 10 MiB decoded response limit, including compressed and chunked downloads. Narrow the saved report if it exceeds that limit. Consume large outputs in code and pass summaries to the agent to control context size.

For reports that take longer to generate:

1. Call hibob_generate_report with report_id, format (csv or xlsx), and optionally include_info/locale.

2. Persist the returned report_name and format. status: "accepted" means generation has started, not that the file is ready.

3. Call hibob_download_generated_report with that name and format. status: "pending" means Bob returned 204; poll the same file later. status: "ready" contains the complete data in the format above.

Each call performs one poll, with no long-running sleep loop. Downloads retry transient HTTP errors using the shared read policy; starting generation is never automatically retried because another request can create another file. Respect the Reports API's 20 requests/minute per endpoint limit. A generated file's availability is controlled by Bob; persist successful downloads if you need reproducible inputs. There is no server-side report cache.

The async endpoint's documented format enum lists CSV/XLSX; JSON is exposed through the direct download endpoint. The returned Location is used only to extract a file name. Downloads always use the configured API host and never follow redirects or send credentials to the supplied location's host.

Reports are saved queries, not a durable event log. The download APIs do not accept an arbitrary since cursor: date conditions belong to the report in Bob. Validate which fields, deleted rows and effective-date changes a report actually includes before treating it as a change feed. Keep downstream processing checkpoints separately.

Official API contracts: list, download, generate, poll, permissions and limits.

Field cheat sheet

Required to create a position:

Updatable on a position: name, effectiveDate, managerPositionId, positionType, fte, employmentType, department, site, jobProfile, reason, plus custom fields (/position/field_<number>, IDs from hibob_get_workforce_form). Custom fields are passed to HiBob unverified: the result names them as undocumented_fields, a rejected update says they may be the reason, and a field HiBob accepted but did not keep shows up in unconfirmed_fields after the read-back. Fields HiBob sets itself (id, status, filledBy, ...) are refused before any request.

Filterable fields: /position/status, /position/name, /position/hasOpenRequests, /position/id; /positionOpening/id, /positionOpening/status (vacant, starting, filled, departing, cancelled, onHold, cancelledSoon), /positionOpening/positionOpeningName. A search without filters returns everything: HiBob refuses an empty filter list, so the server sends a clause every record satisfies.

Fields such as department, site and jobProfile take HiBob list item IDs, not names. hibob_get_workforce_form returns those IDs alongside each field; hibob_get_company_named_lists returns one list's items, or with no list_name just the names and sizes of every list, since the full contents of every list can run to tens of megabytes.

HiBob refuses a write value of the wrong JSON type, at least sometimes with a bare 400 that names no field, so the write tools send each documented field as the type HiBob's API reference gives it. A value is converted where that is unambiguous and refused before the request otherwise:

null is refused for all of them: HiBob allows it only on some creates, where leaving the field out does the same, and never on update. Custom fields (/position/field_<number>) go through as given, since HiBob's reference does not type them.

Tool arguments that name a position, opening, budget or list item take a number as readily as a string, since results show those IDs as numbers. Search filter values go to HiBob as strings, as it compares them, with true/false for yes/no fields.

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