personio-mcp

欠けていたPersonio MCP

注記: これはベータ製品であり、Personioとは一切関係ありません。

Personioの公開APIをツールとして公開するMCPサーバー:

• 採用 (v2): 求人、求人カテゴリ、候補者、応募、ステージ遷移

• 従業員 (v1): 従業員の一覧/取得/作成/更新、欠勤残高、属性カタログ、 プロフィール画像

• 勤怠 (v2): 出勤期間とプロジェクト (CRUD)

• 欠勤 (v1): 休暇タイプ、日単位の休暇、時間単位の欠勤期間

• 文書 (v1): 文書カテゴリ、文書アップロード

• カスタムレポート (v1): レポートメタデータ、レポートデータ、列ラベル

v1の出勤/プロジェクトエンドポイントはPersonioによって非推奨となり(2027-01-31に廃止予定)、 このサーバーはその後継のv2エンドポイント(/v2/attendance-periods、/v2/projects)を使用します。 その他の人事エンドポイントはすべて公式のv1 Personnel Data 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サーバーをサポートしており、 MCP設定をCodex CLIおよびIDE拡張機能と共有します(~/.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を再起動します。コンポーザーで /mcp と入力してサーバーが接続されたことを確認します。

オプションB — UI経由

1. Settings を開き、MCP servers を選択します。

2. Add server を選択します。

3. 名前を入力し(例: personio)、STDIO を選択し、コマンドを npx -y personio-mcp@latest に設定します。

4. 保存して、Restart を選択します。

注: UI経由の場合は、サーバーが起動時に読み取れるようにシェル環境で認証情報を設定してください — または、認証情報をサーバーエントリに限定できるオプション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 — オフセットページネーション。メール / 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リクエスト/分に制限されています。