Skip to main content
Glama
hibob-advanced-mcp

hibob-advanced-mcp

by JustParent

hibob-advanced-mcp

一个用于 HiBob Workforce Planning API 的 MCP 服务器——涵盖计划职位、职位空缺及其预算。

它是对标准 HiBob HRIS 集成的补充,而非替代。常见的 HRIS 功能(人员、休假、文档)属于主集成;此服务器暴露了其他 HRIS 系统中没有对应功能的人力规划表面,因此可以仅为在 HiBob 中规划编制(headcount)的客户启用。

它通过 stdio 运行,可使用 uvx 安装,并使用 HiBob API 服务用户进行身份验证。

HiBob 设置

  1. 在 HiBob 中,转到 设置 → 集成 → API 服务用户 并创建一个服务用户。HiBob 会一次性显示 服务用户 ID 和 令牌——请立即复制两者,因为之后无法再获取。

  2. 创建(或复用)一个包含该服务用户的权限组,并授予:

    功能 → 人力规划 → 职位管理 → 管理职位

    服务用户默认没有任何权限。如果没有此授权,每次调用都会返回 403,此服务器会提示您添加此权限。

  3. 如果您的 HiBob 账户按 IP 地址限制 API 访问,请允许此服务器运行所在位置的出站 IP。

只读使用仍需要相同的授权——HiBob 不提供更窄的人力规划权限。如果您希望服务器本身拒绝进行更改,请使用 HIBOB_READ_ONLY=true(见下文)。

Related MCP server: humaans-mcp

配置

环境变量

必需

描述

HIBOB_SERVICE_USER_ID

是

服务用户 ID(Basic 认证用户名)。

HIBOB_SERVICE_USER_TOKEN

是

服务用户令牌(Basic 认证密码)。

HIBOB_API_HOST

否

默认为生产环境(api.hibob.com)。对于 HiBob 沙箱,设置为 api.sandbox.hibob.com。也接受粘贴的 URL,如 https://api.sandbox.hibob.com/v1;仅使用主机名。

HIBOB_READ_ONLY

否

true、1、yes 或 on 仅注册五个读取工具;八个写入工具完全不暴露。

标准代理变量(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-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>"
      }
    }
  }
}

接入沙箱化的 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 端点

速率限制

hibob_list_workforce_fields

position、positionOpening 或 positionBudget 的元数据

50/分钟

hibob_get_company_named_lists

GET /company/named-lists

—

hibob_search_positions

POST /objects/position/search

100/分钟

hibob_search_position_openings

POST /positions/position-openings/search

100/分钟

hibob_search_position_budgets

POST /positions/position-budget/search

100/分钟

搜索结果以 {"count": N, "entries": [{"values": {...}, "display": {...}}]} 形式返回。values 包含原始值,包括写入工具所需的 ID;display 包含 HiBob 的人类可读标签。空缺和预算搜索是游标分页的,并返回 has_more 和 next_cursor;职位搜索没有分页,因此请只请求您需要的字段,并在可能的地方进行过滤。

写入(设置 HIBOB_READ_ONLY 时省略)

工具

HiBob 端点

速率限制

hibob_create_position

POST /workforce-planning/positions

10/分钟

hibob_update_position

PATCH /workforce-planning/positions/{id}

10/分钟

hibob_cancel_position

PATCH /workforce-planning/positions/{id}/cancel

10/分钟

hibob_create_position_opening

POST .../position-openings

10/分钟

hibob_update_position_opening

PATCH .../position-openings/{openingId}

10/分钟

hibob_delete_position_opening

DELETE .../position-openings/{openingId}

10/分钟

hibob_create_position_budget

POST .../position-budget

10/分钟

hibob_update_position_budget

PATCH .../position-budget/{budgetId}

10/分钟

写入限制为每分钟十次调用,因此在发送请求前会验证必填字段,并且写入调用永远不会自动重试。读取调用在 429 和 5xx 响应时重试两次,并遵守 Retry-After。

hibob_create_position 每次调用创建一个职位,同时创建其第一个空缺(HiBob 要求至少一个)以及可选的预算。

字段速查表

创建职位所需的字段:

对象

必填字段

position

effectiveDate、fte、department、site、jobProfile

positionOpening(嵌套,必需)

expectedStartDate

positionBudget(嵌套,可选)

如果提供预算,则为 salaryPayPeriod、currency

职位上可更新的字段: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]'
pytest

Lint、格式化和类型检查在 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 tools
hibob_cancel_positionA
DestructiveIdempotent

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_openingA
DestructiveIdempotent

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_listsA
Read-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_fieldsA
Read-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_budgetsA
Read-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_openingsA
Read-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_positionsA
Read-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_positionA
Idempotent

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_budgetA
Idempotent

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_openingA
Idempotent

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

    A4.4/5.0

    Scored across 13 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      -
    • A
      license
      B
      quality
      D
      maintenance
      Read-only MCP server for the Humaans HRIS API, providing tools to query people, reporting chains, compensation, time away, and more.
      33
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Read-only MCP server for the Tipsoi HRM API, exposing 15 tools to read employee data, attendance, leave, overtime, and more.
      15
      3
      -