personio-mcp

Недостающий MCP для Personio

Примечание: Это бета-продукт и не связан с Personio.

MCP-сервер, предоставляющий публичные API Personio в виде инструментов:

• Рекрутинг (v2): вакансии, категории вакансий, кандидаты, заявки, переходы по этапам

• Сотрудники (v1): список/получение/создание/обновление сотрудников, балансы отсутствий, каталог атрибутов, фотографии профиля

• Учет рабочего времени (v2): периоды присутствия и проекты (CRUD)

• Отсутствия (v1): типы отгулов, отгулы на основе дней, периоды отсутствия на основе часов

• Документы (v1): категории документов, загрузка документов

• Пользовательские отчеты (v1): метаданные отчетов, данные отчетов, подписи столбцов

Конечные точки v1 для учета рабочего времени/проектов устарели в Personio (прекращение поддержки 2027-01-31), поэтому этот сервер использует их преемников v2 (/v2/attendance-periods, /v2/projects). Все остальные конечные точки для данных о сотрудниках следуют официальному API v1 Personnel Data.

Базовый URL: https://api.personio.de

Учетные данные

1. OAuth2-клиент — в Personio: Marketplace > Connected integrations > Создать пользовательскую интеграцию (требуется тариф Core Pro). Выдает client_id / client_secret. Включите необходимые области/ресурсы API:

   • Рекрутинг: personio:recruiting:read (+ запись для некоторых потоков)

   • Данные о сотрудниках: чтение/запись сотрудников, чтение/запись отсутствий, чтение/запись учета рабочего времени, чтение/запись проектов, чтение/запись документов, чтение пользовательских отчетов Обратите внимание на идентификатор компании интеграции — он требуется для всех конечных точек данных о сотрудниках.

2. Токен рекрутинга (нужен только для personio_create_application) — статический токен в разделе Settings > Integrations > API Credentials. Идентификатор компании виден по адресу 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 — через интерфейс

1. Откройте Настройки, затем выберите MCP-серверы.

2. Выберите Добавить сервер.

3. Введите имя (например, personio), выберите STDIO и укажите команду npx -y personio-mcp@latest.

4. Сохраните, затем выберите Перезапустить.

Примечание: если вы используете интерфейс, задайте учетные данные в переменных окружения вашей оболочки, чтобы сервер мог прочитать их при запуске — или предпочтите вариант 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 (макс. 30 МБ)

Пользовательские отчеты:

• personio_list_custom_reports, personio_get_custom_report, personio_list_report_columns

Примечания из API Personio:

• Конечные точки v2 (рекрутинг, периоды присутствия, проекты) используют постраничную выдачу на основе курсора; инструменты возвращают pagination.next_cursor.

• Конечные точки v1 для данных о сотрудниках используют постраничную выдачу со смещением; инструменты возвращают pagination.total_elements / pagination.next_offset.

• Сотрудники/заявки не предоставляют пользовательские атрибуты или теги через v2.

• Электронные письма сотрудников нельзя изменить после создания.

• Создание заявки работает только для текущих опубликованных вакансий и ограничено по частоте ~100 заявок/мин на IP.

• Загрузка документов ограничена ~60 запросов/мин.