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（见下文）。

配置

标准代理变量（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": ...} 信封中，并将搜索结果扁平化返回。

读取

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

写入（设置 HIBOB_READ_ONLY 时省略）

写入限制为每分钟十次调用，因此在发送请求前会验证必填字段，并且写入调用永远不会自动重试。读取调用在 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]'
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