personio-mcp

없었던 Personio MCP

참고: 이 제품은 베타 버전이며 Personio와 어떤 관련도 없습니다.

Personio의 공개 API를 도구로 노출하는 MCP 서버:

• Recruiting (v2): 채용 공고, 채용 카테고리, 지원자, 지원서, 단계 전환

• Employees (v1): 직원 목록/조회/생성/수정, 휴가 잔액, 속성 카탈로그, 프로필 사진

• Time tracking (v2): 출퇴근 기간 및 프로젝트 (CRUD)

• Absences (v1): 휴가 유형, 일 단위 휴가, 시간 단위 부재 기간

• Documents (v1): 문서 카테고리, 문서 업로드

• Custom reports (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 리소스를 활성화하세요:

   • Recruiting: personio:recruiting:read (+ 일부 흐름에는 쓰기)

   • Personnel data: 직원 읽기/쓰기, 휴가 읽기/쓰기, 출퇴근 읽기/쓰기, 프로젝트 읽기/쓰기, 문서 읽기/쓰기, 커스텀 리포트 읽기 통합의 company ID를 기록하세요 — 모든 인사 데이터 엔드포인트에 필요합니다.

2. Recruiting 토큰 (personio_create_application에만 필요) — Settings > Integrations > API Credentials 아래의 정적 토큰. company 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. 설정을 열고 MCP 서버를 선택합니다.

2. 서버 추가를 선택합니다.

3. 이름(예: personio)을 입력하고 STDIO를 선택한 다음 명령을 npx -y personio-mcp@latest로 설정합니다.

4. 저장한 다음 다시 시작을 선택합니다.

참고: 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건으로 제한됩니다.