hibob-advanced-mcp
hibob-advanced-mcp
一个用于 HiBob Workforce Planning API 的 MCP 服务器——涵盖计划职位、职位空缺及其预算。
它是对标准 HiBob HRIS 集成的补充,而非替代。常见的 HRIS 功能(人员、休假、文档)属于主集成;此服务器暴露了其他 HRIS 系统中没有对应功能的人力规划表面,因此可以仅为在 HiBob 中规划编制(headcount)的客户启用。
它通过 stdio 运行,可使用 uvx 安装,并使用 HiBob API 服务用户进行身份验证。
HiBob 设置
在 HiBob 中,转到 设置 → 集成 → API 服务用户 并创建一个服务用户。HiBob 会一次性显示 服务用户 ID 和 令牌——请立即复制两者,因为之后无法再获取。
创建(或复用)一个包含该服务用户的权限组,并授予:
功能 → 人力规划 → 职位管理 → 管理职位
服务用户默认没有任何权限。如果没有此授权,每次调用都会返回 403,此服务器会提示您添加此权限。
如果您的 HiBob 账户按 IP 地址限制 API 访问,请允许此服务器运行所在位置的出站 IP。
只读使用仍需要相同的授权——HiBob 不提供更窄的人力规划权限。如果您希望服务器本身拒绝进行更改,请使用 HIBOB_READ_ONLY=true(见下文)。
Related MCP server: humaans-mcp
配置
环境变量 | 必需 | 描述 |
| 是 | 服务用户 ID(Basic 认证用户名)。 |
| 是 | 服务用户令牌(Basic 认证密码)。 |
| 否 | 默认为生产环境( |
| 否 |
|
标准代理变量(HTTPS_PROXY、ALL_PROXY)会被遵守。SOCKS5 代理需要可选的 socks 附加项——请参阅下面的安装行。
运行
固定到某个提交,这是部署时应采用的方式:
uvx --from 'git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>' hibob-advanced-mcp从本地检出,在开发期间:
uvx --from . hibob-advanced-mcp --test--test 打印版本、解析后的 API 基础 URL、是否设置了凭据(绝不打印其值)、只读状态以及每个已注册的工具,然后退出。它无需 MCP 客户端或实时凭据即可验证安装。
使用 SOCKS5 代理:
uvx --from 'git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>[socks]' hibob-advanced-mcpClaude 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>"
}
}
}
}接入沙箱化的 MCP 集成
对于使用 Claude Desktop 配置形状将 MCP 服务器作为沙箱子进程运行的主机,集成配置为:
{
"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"
}
}将服务用户的令牌粘贴到集成的密钥字段中:$SECRET_KEY 会在沙箱内被替换为它,因此令牌永远不会存储在配置本身中。服务用户 ID 不是机密,可以直接写入。
无需 --with 'mcp<2' 参数——此包已固定 MCP SDK 本身。
工具
字段 ID 以扁平映射传递,例如 {"/position/fte": 100}。/position/ 前缀可以省略({"fte": 100})。服务器会为您将值包装到 HiBob 的 {"value": ...} 信封中,并将搜索结果扁平化返回。
读取
工具 | HiBob 端点 | 速率限制 |
|
| 50/分钟 |
|
| — |
|
| 100/分钟 |
|
| 100/分钟 |
|
| 100/分钟 |
搜索结果以 {"count": N, "entries": [{"values": {...}, "display": {...}}]} 形式返回。values 包含原始值,包括写入工具所需的 ID;display 包含 HiBob 的人类可读标签。空缺和预算搜索是游标分页的,并返回 has_more 和 next_cursor;职位搜索没有分页,因此请只请求您需要的字段,并在可能的地方进行过滤。
写入(设置 HIBOB_READ_ONLY 时省略)
工具 | HiBob 端点 | 速率限制 |
|
| 10/分钟 |
|
| 10/分钟 |
|
| 10/分钟 |
|
| 10/分钟 |
|
| 10/分钟 |
|
| 10/分钟 |
|
| 10/分钟 |
|
| 10/分钟 |
写入限制为每分钟十次调用,因此在发送请求前会验证必填字段,并且写入调用永远不会自动重试。读取调用在 429 和 5xx 响应时重试两次,并遵守 Retry-After。
hibob_create_position 每次调用创建一个职位,同时创建其第一个空缺(HiBob 要求至少一个)以及可选的预算。
字段速查表
创建职位所需的字段:
对象 | 必填字段 |
|
|
|
|
| 如果提供预算,则为 |
职位上可更新的字段:name、effectiveDate、managerPositionId、positionType、fte、employmentType、department、site、jobProfile、reason。
可过滤字段:/position/status、/position/name、/position/hasOpenRequests、/position/id;/positionOpening/id、/positionOpening/status(vacant、starting、filled、departing)、/positionOpening/positionOpeningName。
诸如 department、site 和 jobProfile 等字段接受 HiBob 列表项 ID,而不是名称。在创建或更新职位之前,请使用 hibob_get_company_named_lists 解析它们。
开发
uv venv
uv pip install -e '.[test,lint,typecheck]'
pytestLint、格式化和类型检查在 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类型检查特意采用非严格模式——注释存在的地方会被检查,但允许无类型代码。包附带 py.typed 标记,因此其注释对任何导入它的内容都可见。
交互式检查工具:
npx @modelcontextprotocol/inspector uvx --from . hibob-advanced-mcp许可证
MIT
Available Tools
13 toolshibob_cancel_positionADestructiveIdempotent
Cancel a planned position, removing it from the workforce plan.
HiBob refuses to cancel a position that is currently filled; check '/position/status' with hibob_search_positions first. Cancelling cannot be undone through this API, so confirm the position ID before calling.
Args: position_id: The position's ID.
Returns: str: JSON confirming the cancellation, or an error message beginning with "Error:".
Rate limit: 10 requests/minute.
Inputs: position_id (required). Returns: result
hibob_create_positionA
Create a planned position, with its opening and optional budget.
A position is a budgeted seat in the plan; every position must be created with an opening, which is the vacancy to be filled. Field values that reference HiBob lists (department, site, job profile) must be the list item IDs - resolve them first with hibob_get_company_named_lists and hibob_list_workforce_fields.
Creates one position per call. Required fields are checked before the request is sent, because HiBob allows only ten write calls per minute.
Args: position_fields: Flat mapping of position field IDs to values. opening_fields: Flat mapping for the nested opening. budget_fields: Optional flat mapping for the nested budget.
Returns: str: JSON {"id": int, "positionOpeningId": int} identifying the new position, or an error message beginning with "Error:".
Examples: - "Plan a new engineer starting in September" -> position_fields with effectiveDate/fte/department/site/jobProfile plus opening_fields with expectedStartDate. - Don't use when: adding a second vacancy to an existing position (use hibob_create_position_opening).
Rate limit: 10 requests/minute.
Inputs: opening_fields (required), position_fields (required), budget_fields. Returns: result
hibob_create_position_budgetA
Attach a salary and cost budget to a position.
Args: position_id: The position's ID. fields: Flat mapping of budget field IDs to values.
Returns: str: JSON {"positionBudgetId": int}, or an error message beginning with "Error:".
Examples: - "Budget 65k a year for that role" -> fields with expectedBaseSalaryCurrencyValue, salaryPayPeriod and currency.
Rate limit: 10 requests/minute.
Inputs: fields (required), position_id (required). Returns: result
hibob_create_position_openingA
Add a vacancy to an existing position.
Args: position_id: The parent position's ID. fields: Flat mapping of opening field IDs to values.
Returns: str: JSON {"id": int, "positionOpeningId": int}, or an error message beginning with "Error:".
Rate limit: 10 requests/minute.
Inputs: fields (required), position_id (required). Returns: result
hibob_delete_position_openingADestructiveIdempotent
Permanently remove an opening from a position.
This deletes the vacancy record in HiBob and cannot be undone through this API. Confirm the opening ID with hibob_search_position_openings before calling.
Args: position_id: Parent position ID. opening_id: The opening's ID.
Returns: str: JSON confirming the deletion, or an error message beginning with "Error:".
Rate limit: 10 requests/minute.
Inputs: opening_id (required), position_id (required). Returns: result
hibob_get_company_named_listsARead-onlyIdempotent
Look up the allowed values of HiBob's named lists.
Position fields such as department, site and employment type must be set to a list item from HiBob's named lists rather than to free text. This tool resolves those names to the IDs that hibob_create_position and hibob_update_position expect.
Args: list_name: A single list to fetch, or None for all lists.
Returns: str: JSON mapping list names to their items, each with an ID and a display name.
Examples: - "Which departments exist?" -> list_name='department' - Use before hibob_create_position to turn "Engineering" into its list item ID.
Inputs: list_name. Returns: result
hibob_list_workforce_fieldsARead-onlyIdempotent
List the fields available on a HiBob workforce planning object.
Call this before searching or creating anything: it returns the field IDs (such as '/position/fte') that every other tool in this server expects, along with each field's type and whether it is required.
Args: object_type: 'position', 'positionOpening' or 'positionBudget'.
Returns: str: JSON describing the available fields, as returned by HiBob.
Examples: - "What can I set on a position?" -> object_type='position' - "What does a budget need?" -> object_type='positionBudget' - Don't use when: you need the allowed values of a list field such as department or site (use hibob_get_company_named_lists).
Rate limit: 50 requests/minute.
Inputs: object_type. Returns: result
hibob_search_position_budgetsARead-onlyIdempotent
Search position budgets: planned salary and total cost per position.
Use this for cost roll-ups across planned headcount, such as the total budgeted cost of every vacant position in a department.
Args: fields: Field IDs to return (1-50). filters: Optional filter clauses. limit: Page size, 1-100. cursor: Cursor from a previous page, or None to start. include_human_readable: Include display labels.
Returns: str: JSON of the form {"count": int, "entries": [...], "has_more": bool, "next_cursor": str}.
Rate limit: 100 requests/minute.
Inputs: fields (required), limit, cursor, filters, +1 more. Returns: result
hibob_search_position_openingsARead-onlyIdempotent
Search position openings, the vacancies attached to positions.
Openings carry the recruitment view of a position: expected start date, recruitment status and whether the seat is vacant, starting, filled or departing.
Args: fields: Field IDs to return (1-50). filters: Optional filter clauses. limit: Page size, 1-100. cursor: Cursor from a previous page, or None to start. include_human_readable: Include display labels.
Returns: str: JSON of the form {"count": int, "entries": [...], "has_more": bool, "next_cursor": str}. When "has_more" is true, call again passing "next_cursor" to retrieve the rest.
Examples: - "Which openings are still vacant?" -> filters=[{field_id: '/positionOpening/status', operator: 'equals', values: ['vacant']}]
Rate limit: 100 requests/minute.
Inputs: fields (required), limit, cursor, filters, +1 more. Returns: result
hibob_search_positionsARead-onlyIdempotent
Search the company's positions.
Returns one entry per matching position. Each entry has 'values' (the raw values, including the IDs needed by the update tools) and 'display' (human-readable labels).
This endpoint has no pagination, so always request only the fields you need and filter where possible in a large organization.
Args: fields: Field IDs to return (1-50). filters: Optional filter clauses combined by HiBob. include_human_readable: Include display labels alongside raw values.
Returns: str: JSON of the form {"count": int, "entries": [{"values": {...}, "display": {...}}]}, or an error message beginning with "Error:".
Examples: - "Which positions are vacant?" -> fields=['/position/id', '/position/name'], filters=[{field_id: '/position/status', operator: 'equals', values: ['vacant']}] - Don't use when: you need opening-level detail such as expected start dates (use hibob_search_position_openings).
Rate limit: 100 requests/minute.
Inputs: fields (required), filters, include_human_readable. Returns: result
hibob_update_positionAIdempotent
Change details of an existing position.
Only the fields supplied are modified. Use hibob_search_positions to find the position ID first.
Args: position_id: The position's ID. fields: Flat mapping of field IDs to new values.
Returns: str: JSON confirming the update, or an error message beginning with "Error:".
Examples: - "Move that position's start to October" -> fields with '/position/effectiveDate'.
Rate limit: 10 requests/minute.
Inputs: fields (required), position_id (required). Returns: result
hibob_update_position_budgetAIdempotent
Change an existing position budget.
Use hibob_search_position_budgets to find the budget ID.
Args: position_id: Parent position ID. budget_id: The budget's ID. fields: Flat mapping of field IDs to new values.
Returns: str: JSON confirming the update, or an error message beginning with "Error:".
Rate limit: 10 requests/minute.
Inputs: fields (required), budget_id (required), position_id (required). Returns: result
hibob_update_position_openingAIdempotent
Change an existing opening, such as its expected start date or recruitment status.
Args: position_id: Parent position ID. opening_id: The opening's ID. fields: Flat mapping of field IDs to new values.
Returns: str: JSON confirming the update, or an error message beginning with "Error:".
Rate limit: 10 requests/minute.
Inputs: fields (required), opening_id (required), position_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct resource-action pair: positions, openings, budgets, and metadata lookups are clearly separated. The naming and descriptions make it easy to pick the right tool, even for close operations like create_position vs create_position_opening.
All tools follow a consistent hibob_verb_noun pattern with snake_case throughout, e.g., hibob_search_positions, hibob_create_position_budget, hibob_delete_position_opening. Resource terms are plural and actions are predictable across the set.
Thirteen tools is well-scoped for a workforce planning server covering positions, openings, budgets, and supporting metadata lookups. Each tool earns its place and the count is neither bloated nor thin.
The server covers core lifecycle operations for positions, openings, and budgets, including search, create, update, and delete/cancel where relevant. A minor gap is the absence of a delete operation for position budgets, though create and update are covered.
Maintenance
Related MCP Connectors
MCP server for Arcoro and ExakTime — workforce data, jobs, cost codes and locations.
isolved and ApplicantPro jobs, tenant discovery, and change detection as an MCP server.
MCP server for SmartHR — employees, departments, dependents and employee invitations.
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP Server that provides access to Personio's HR and personnel data through the Personnel API, allowing interaction with employee records, HR systems, and personnel management functions.-
- AlicenseBqualityDmaintenanceRead-only MCP server for the Humaans HRIS API, providing tools to query people, reporting chains, compensation, time away, and more.33MIT
- FlicenseAqualityDmaintenanceRead-only MCP server for the Tipsoi HRM API, exposing 15 tools to read employee data, attendance, leave, overtime, and more.153-
- AlicenseNot gradedqualityDmaintenanceThis MCP server enables AI-assisted professional profile generation by connecting to verified employee work data (skills, career history, certifications, projects) from employer HCM systems.MIT