personio-mcp

El MCP de Personio que faltaba

Nota: Este es un producto beta y no está afiliado a Personio de ninguna manera.

Servidor MCP que expone las API públicas de Personio como herramientas:

• Reclutamiento (v2): puestos de trabajo, categorías de puestos, candidatos, solicitudes, transiciones de etapa

• Empleados (v1): listar/obtener/crear/actualizar empleados, saldos de ausencias, catálogo de atributos, fotos de perfil

• Registro de tiempo (v2): períodos de asistencia y proyectos (CRUD)

• Ausencias (v1): tipos de tiempo libre, ausencias basadas en días, períodos de ausencia basados en horas

• Documentos (v1): categorías de documentos, cargas de documentos

• Informes personalizados (v1): metadatos de informes, datos de informes, etiquetas de columnas

Los endpoints v1 de asistencia/proyectos están obsoletos por Personio (fin de vida 2027-01-31), por lo que este servidor usa sus sucesores v2 (/v2/attendance-periods, /v2/projects). Todos los demás endpoints de personal siguen la API oficial de Datos de Personal v1.

URL base: https://api.personio.de

Credenciales

1. Cliente OAuth2 — en Personio: Marketplace > Integraciones conectadas > Crear integración personalizada (requiere plan Core Pro). Te proporciona client_id / client_secret. Habilita los alcances/recursos de API que necesites:

   • Reclutamiento: personio:recruiting:read (+ escritura para algunos flujos)

   • Datos de personal: lectura/escritura de empleados, lectura/escritura de ausencias, lectura/escritura de asistencia, lectura/escritura de proyectos, lectura/escritura de documentos, lectura de informes personalizados Ten en cuenta el ID de empresa de la integración — es obligatorio para todos los endpoints de datos de personal.

2. Token de reclutamiento (solo necesario para personio_create_application) — token estático en Configuración > Integraciones > Credenciales de API. El ID de empresa es visible en https://{YOUR_COMPANY}.personio.de/configuration/api/credentials/management.

Related MCP server: Employee Management MCP Server

Variables de entorno

Uso

Requiere Node.js 20+. Ejecuta directamente con npx (sin necesidad de instalación):

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

Configuración del cliente (p. ej. Claude Desktop / opencode)

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

Aplicación de escritorio de ChatGPT

La nueva aplicación de escritorio de ChatGPT admite servidores MCP locales STDIO y comparte su configuración de MCP con Codex CLI y la extensión del IDE (almacenada en ~/.codex/config.toml).

Opción A — mediante config.toml (recomendada, ya que te permite establecer variables de entorno)

Añade esto a ~/.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 = "..."

Luego reinicia ChatGPT. Escribe /mcp en el compositor para verificar que el servidor se ha conectado.

Opción B — mediante la interfaz de usuario

1. Abre Configuración y luego selecciona Servidores MCP.

2. Selecciona Añadir servidor.

3. Introduce un nombre (p. ej. personio), elige STDIO y establece el comando como npx -y personio-mcp@latest.

4. Guarda y luego selecciona Reiniciar.

Nota: si usas la interfaz de usuario, establece las credenciales en el entorno de tu shell para que el servidor pueda leerlas al iniciarse — o prefiere la Opción A, que mantiene las credenciales limitadas a la entrada del servidor.

Herramientas

Salud y reclutamiento:

• personio_health_check — verifica que las credenciales funcionan

• 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 — envía una solicitud (v1); requiere las variables de entorno adicionales anteriores

Empleados:

• personio_list_employees — paginado por desplazamiento; filtra por email / updated_since / attributes[]

• personio_get_employee, personio_create_employee, personio_update_employee

• personio_get_employee_absence_balance

• personio_list_employee_attributes — catálogo de atributos incl. campos personalizados (dinámicos)

• personio_get_profile_picture — devuelve el contenido de la imagen; ancho opcional

Registro de tiempo:

• personio_list_attendance_periods — paginado por cursor; filtros ricos (persona, proyecto, fechas, estado)

• 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

Ausencias:

• personio_list_time_off_types — incluye unidad (día/hora) y requisitos de aprobación

• personio_list_time_offs, personio_create_time_off, personio_get_time_off, personio_delete_time_off — ausencias basadas en días

• personio_list_absence_periods, personio_create_absence_period, personio_delete_absence_period — ausencias basadas en horas

Documentos:

• personio_list_document_categories

• personio_upload_document — carga multiparte; pasa contenido de texto o base64 (máx. 30MB)

Informes personalizados:

• personio_list_custom_reports, personio_get_custom_report, personio_list_report_columns

Notas de la API de Personio:

• Los endpoints v2 (reclutamiento, períodos de asistencia, proyectos) están paginados por cursor; las herramientas devuelven pagination.next_cursor.

• Los endpoints v1 de personal están paginados por desplazamiento; las herramientas devuelven pagination.total_elements / pagination.next_offset.

• Los empleados/solicitudes no exponen atributos personalizados ni etiquetas a través de v2.

• Los correos electrónicos de los empleados no se pueden cambiar después de la creación.

• La creación de solicitudes solo funciona para puestos publicados actualmente y está limitada a ~100 solicitudes/min por IP.

• Las cargas de documentos están limitadas a ~60 solicitudes/min.