personio-mcp

缺失的 Personio MCP

注意： 这是一个测试版产品，与 Personio 没有任何关联。

MCP 服务器，将 Personio 的公共 API 暴露为工具：

• 招聘 (v2)：职位、职位类别、候选人、申请、阶段转换

• 员工 (v1)：列出/获取/创建/更新员工、缺勤余额、属性目录、头像

• 时间跟踪 (v2)：出勤时段和项目（增删改查）

• 缺勤 (v1)：休假类型、按天计算的休假、按小时计算的缺勤时段

• 文档 (v1)：文档类别、文档上传

• 自定义报告 (v1)：报告元数据、报告数据、列标签

v1 的出勤/项目端点已被 Personio 弃用（2027-01-31 停止服务），因此此服务器使用其 v2 后继端点（/v2/attendance-periods、/v2/projects）。所有其他人事端点遵循官方 v1 人事数据 API。

基础 URL：https://api.personio.de

凭据

1. OAuth2 客户端 — 在 Personio 中：Marketplace > Connected integrations > Create custom integration（需要 Core Pro 计划）。获取 client_id / client_secret。启用你需要的范围/API 资源：

   • 招聘：personio:recruiting:read（某些流程需要写入权限）

   • 人事数据：员工读写、缺勤读写、出勤读写、项目读写、文档读写、自定义报告读取 注意集成的公司 ID — 所有人事数据端点都需要它。

2. 招聘令牌（仅 personio_create_application 需要）— 在 Settings > Integrations > API Credentials 下的静态令牌。公司 ID 可在 https://{YOUR_COMPANY}.personio.de/configuration/api/credentials/management 查看。

Related MCP server: Employee Management MCP Server

环境变量

用法

需要 Node.js 20+。直接用 npx 运行（无需安装）：

PERSONIO_CLIENT_ID=... PERSONIO_CLIENT_SECRET=... PERSONIO_COMPANY_ID=... npx -y personio-mcp@latest

客户端配置（例如 Claude Desktop / opencode）

{
  "mcpServers": {
    "personio": {
      "command": "npx",
      "args": ["-y", "personio-mcp@latest"],
      "env": {
        "PERSONIO_CLIENT_ID": "...",
        "PERSONIO_CLIENT_SECRET": "...",
        "PERSONIO_COMPANY_ID": "..."
      }
    }
  }
}

ChatGPT 桌面应用

新的 ChatGPT 桌面应用支持本地 STDIO MCP 服务器，并与 Codex CLI 和 IDE 扩展共享其 MCP 配置（存储在 ~/.codex/config.toml 中）。

选项 A — 通过 config.toml（推荐，因为可以设置环境变量）

将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.personio]
command = "npx"
args = ["-y", "personio-mcp@latest"]

[mcp_servers.personio.env]
PERSONIO_CLIENT_ID = "..."
PERSONIO_CLIENT_SECRET = "..."
PERSONIO_COMPANY_ID = "..."
# Only needed for personio_create_application:
# PERSONIO_RECRUITING_TOKEN = "..."

然后重启 ChatGPT。在 composer 中输入 /mcp 以验证服务器已连接。

选项 B — 通过 UI

1. 打开 Settings，然后选择 MCP servers。

2. 选择 Add server。

3. 输入名称（例如 personio），选择 STDIO，并将命令设置为 npx -y personio-mcp@latest。

4. 保存，然后选择 Restart。

注意：如果通过 UI 操作，请在 shell 环境中设置凭据，以便服务器在启动时读取它们 — 或者更推荐选项 A，它可以将凭据限定在服务器条目内。

工具

健康检查与招聘：

• personio_health_check — 验证凭据是否有效

• personio_list_jobs、personio_get_job

• personio_list_job_categories、personio_get_job_category

• personio_list_candidates、personio_get_candidate

• personio_list_applications、personio_get_application、personio_list_application_stage_transitions

• personio_create_application — 提交申请（v1）；需要上述额外的环境变量

员工：

• personio_list_employees — 偏移分页；按 email / updated_since / attributes[] 过滤

• personio_get_employee、personio_create_employee、personio_update_employee

• personio_get_employee_absence_balance

• personio_list_employee_attributes — 属性目录，包括自定义（动态）字段

• personio_get_profile_picture — 返回图像内容；可选宽度

时间跟踪：

• personio_list_attendance_periods — 游标分页；丰富的过滤器（人员、项目、日期、状态）

• personio_get_attendance_period、personio_create_attendance_period、personio_update_attendance_period、personio_delete_attendance_period

• personio_list_projects、personio_get_project、personio_create_project、personio_update_project、personio_delete_project

缺勤：

• personio_list_time_off_types — 包括单位（天/小时）和审批要求

• personio_list_time_offs、personio_create_time_off、personio_get_time_off、personio_delete_time_off — 按天计算的休假

• personio_list_absence_periods、personio_create_absence_period、personio_delete_absence_period — 按小时计算的缺勤时段

文档：

• personio_list_document_categories

• personio_upload_document — 多部分上传；传递文本或 base64 内容（最大 30MB）

自定义报告：

• personio_list_custom_reports、personio_get_custom_report、personio_list_report_columns

来自 Personio API 的说明：

• v2 端点（招聘、出勤时段、项目）使用游标分页；工具返回 pagination.next_cursor。

• v1 人事端点使用偏移分页；工具返回 pagination.total_elements / pagination.next_offset。

• 员工/申请不通过 v2 暴露自定义属性或标签。

• 员工电子邮件在创建后无法更改。

• 申请创建仅适用于当前已发布的职位，并且每个 IP 的速率限制约为每分钟 100 个申请。

• 文档上传限制约为每分钟 60 个请求。