MCP GLPI Server

Servidor de referencia para integrar el ecosistema Model Context Protocol (MCP) con GLPI. Proporciona herramientas de gestion de tickets, cambios y sesion listas para usar en flujos de automatizacion, junto con utilidades para validacion y soporte.

• Implementacion MCP sobre stdio lista para Claude Desktop y otros clientes compatibles.
• Coleccion de herramientas GLPI para listar, crear, actualizar y relacionar tickets y cambios, ademas de operaciones de sesion del usuario logueado.
• Subida y descarga de archivos (Document de GLPI), y vinculo/desvinculo de documentos con tickets y cambios.
• Recurso MCP (resources/list + resources/read) con una guia de uso de las herramientas de elementos/archivos GLPI, para que el cliente MCP la cargue como contexto de referencia.
• Validacion de configuracion impulsada por Pydantic y uso de variables de entorno con .env.
• Respuestas normalizadas en JSON para facilitar integracion con clientes MCP y automatizaciones.
• Organizacion modular por paquetes (tickets/, changes/, session/) para extender nuevas funcionalidades con menor acoplamiento.
• Suite de pruebas unitarias (pytest) que cubre el manejador de comandos, los helpers GLPI y la documentacion del repositorio.

1. Clonar el repositorio y crear un entorno virtual:

   python -m venv .venv
   .venv/Scripts/activate  # Windows
   # source .venv/bin/activate  # Linux/macOS

2. Instalar dependencias:

   pip install -e .

3. Configurar credenciales GLPI (tokens y URL):
   • Definir las variables GLPI_URL, GLPI_APP_TOKEN y GLPI_USER_TOKEN en el entorno.
   • Alternativamente, crear un archivo .env en la raiz del proyecto con esos valores.

Las herramientas expuestas por GLPITools se registran automaticamente en el servidor MCP. Los nombres siguen la convencion elemento_funcion / elemento_subelemento_funcion (ver detalle y motivacion en la nota de documentacion Documentacion MCP-GLPI.md):

ticket_follow_list/change_follow_list y ticket_solution_list/change_solution_list listan los sub-items (ITILFollowup/ITILSolution) de un ticket o cambio puntual. Aceptan ticket_id/change_id (obligatorio), limit, offset, sort_by, order, output (dict/table/raw), fields, y los mismos entity_id/profile_id opcionales descritos abajo. No soportan filters/expand_dropdowns/include_deleted porque la API de sub-items de GLPI no los expone.

Ademas de las herramientas especificas, hay herramientas de acceso generico a cualquier itemtype/subtype soportado, sin necesidad de una tool nueva por combinacion. Las tres primeras son de solo lectura; item_delete es la unica mutacion generica:

• item_list(itemtype, ...): lista elementos del itemtype (equivalente a GET /{itemtype}), con limit/offset/sort_by/order/filters/output/fields. No lleva id.
• item_get(itemtype, id, ...): obtiene un elemento puntual por id (GET /{itemtype}/{id}), con fields/expand_dropdowns. id es obligatorio.
• item_subitem_list(itemtype, id, subtype, ...): lista sub-items de un elemento (GET /{itemtype}/{id}/{subtype}).
• item_delete(itemtype, id, ...): elimina un elemento (equivalente a DELETE /{itemtype}/{id}), con purge/keep_history igual que ticket_delete/change_delete.
• item_type_list / item_subtype_list: devuelven los itemtypes/subtypes soportados, cada uno con una breve descripcion, para saber que valores son validos antes de llamar a las anteriores.

Los itemtypes/subtypes soportados son una lista blanca deliberada (hoy: Ticket, Change, Document, y sus sub-recursos ya cubiertos por las herramientas especificas — ITILFollowup, ITILSolution, Ticket_User, Group_Ticket, Change_User, Change_Group, Change_Ticket, Document_Item). Un itemtype/subtype fuera de esa lista (por ejemplo User, Config, Computer) devuelve un error de validacion en vez de ejecutarse — este servidor no expone datos de GLPI mas alla de tickets/cambios y sus relaciones, ni siquiera a traves de la ruta generica.

item_list(itemtype="Document", ...) / item_get(itemtype="Document", id=...) permiten buscar/consultar metadata de documentos (nombre, filename, mime, entidad, fecha), e item_subitem_list(itemtype="Ticket"|"Change", id=..., subtype="Document_Item") muestra que documentos ya estan vinculados a un ticket o cambio puntual — sin necesidad de una tool dedicada para listar/buscar documentos.

• file_upload(file_path, ...): sube un archivo como Document de GLPI (POST Document/ multipart/form-data). file_path es una ruta local en el sistema de archivos de la maquina donde corre el servidor MCP; file_name por defecto es el nombre base de file_path.
• file_download(document_id, destination_path, ...): descarga un Document (GET Document/:id con Accept: application/octet-stream) y escribe los bytes en destination_path (ruta local, se crean los directorios padre si hace falta).
• file_link(document_id, item_type, item_id, ...) / file_unlink(document_id, link_id, ...): crean/eliminan la relacion Document_Item entre un documento y un ticket o cambio. item_type esta restringido al mismo ITEMTYPE_CATALOG que gobierna las herramientas genericas.

Las cuatro aceptan los mismos entity_id/profile_id opcionales que el resto de las herramientas.

Todas las herramientas que operan sobre un ticket o cambio (creacion, listados, comentarios, soluciones, asignaciones, enlaces, actualizacion y borrado) aceptan dos parametros opcionales:

• entity_id: cambia la entidad activa de la sesion GLPI (via changeActiveEntities) antes de ejecutar la operacion. El codigo 0 (entidad raiz de GLPI) es un valor valido. Use entity_list para consultar los codigos disponibles.
• profile_id: cambia el perfil activo de la sesion GLPI (via changeActiveProfile) antes de ejecutar la operacion. Use profile_list para consultar los codigos disponibles.

Si se omiten (o llegan vacios/null), se usan el perfil/entidad activos por defecto de la sesion sin fallar. Cuando se indican ambos en la misma llamada, el perfil se cambia primero y luego la entidad: el perfil activo determina los permisos (crear/leer/editar) con los que se ejecuta la operacion; la entidad activa solo determina sobre que registros se opera. En GLPI, las entidades a las que un usuario tiene acceso estan asociadas a sus perfiles (ver la respuesta de profile_list) — para operar correctamente sobre una entidad que pertenece a un perfil distinto al activo, pase tambien profile_id.

Ambos parametros tambien aceptan el nombre de la entidad/perfil (texto no numerico) en vez del id: se resuelve automaticamente consultando profile_list internamente, y si solo se da el nombre del perfil (sin entidad), se selecciona la primera entidad de ese perfil. La respuesta incluye un campo resolution_notes cuando esto ocurre. Un nombre ambiguo (coincide con mas de un perfil/entidad) o inexistente devuelve un error de validacion en vez de adivinar. Ver el recurso mcp-glpi://docs/glpi-entity-profile-resolution para el detalle completo.

Como cada llamada MCP abre y cierra su propia sesion GLPI, el cambio de entidad/perfil aplica solo a esa llamada puntual; no persiste para llamadas posteriores.

Importante: GLPI responde HTTP 200 con cuerpo false (no un error HTTP) cuando la entidad o el perfil indicados no son accesibles para el usuario/token, o no existen. Cualquier herramienta invocada con entity_id/profile_id detecta este caso y devuelve un error explicito en vez de fallar en silencio; si obtenes ese error, revisa que el entity_id/profile_id este entre los que devuelve entity_list/profile_list.

Nota de diseño: no hay herramientas dedicadas entity_switch/profile_switch — cada llamada MCP abre y cierra su propia sesion GLPI, asi que "cambiar de entidad/perfil" como operacion aislada no tendria ningun efecto persistente. Cambiar de entidad/perfil solo tiene sentido junto con la operacion real que se quiere ejecutar en esa entidad/perfil, por eso entity_id/profile_id son parametros de las herramientas de negocio (ticket_list, ticket_add, etc.), no tools independientes.

Las herramientas responden en JSON serializado dentro de TextContent. Por ejemplo, profile_list devuelve una lista simplificada de perfiles:

[
  {
    "id": 22,
    "name": "Administrativo - Solicitante",
    "entities": [
      {
        "id": 2,
        "name": "Administrativo",
        "is_recursive": true
      }
    ]
  }
]

Ademas de las tools, el servidor expone la capacidad resources del protocolo MCP (resources/list / resources/read), para que un cliente MCP pueda cargar documentacion de referencia como contexto sin necesidad de invocar una tool.

• src/mcp_glpi/resource_catalog.py: fuente unica de verdad de los recursos publicados (RESOURCE_SPECS: uri/name/description/mime_type/path), analogo a TOOL_SPECS en tool_catalog.py.
• src/mcp_glpi/resources/: contenido real de los recursos (archivos .md), empaquetado dentro del wheel via [tool.setuptools.package-data] en pyproject.toml.
• src/mcp_glpi/server.py: registra handle_list_resources/handle_read_resource sobre self.app, leyendo el contenido con resource_catalog.read_resource_text(uri).

Recursos publicados hoy (separados por tema para poder cargar solo el que aplica):

Para agregar un recurso nuevo: colocar el archivo en src/mcp_glpi/resources/, agregar una entrada a RESOURCE_SPECS, y (si es un patron de archivo nuevo, ej. .json) ajustar el glob en [tool.setuptools.package-data].

Ejecutar en modo CLI:

python -m mcp_glpi.server
# o con logging detallado
python -m mcp_glpi.server --verbose

Para integrarlo con Claude Desktop, utilice examples/claude_desktop_config.json como guia. Ajuste la ruta del ejecutable y el cwd segun su entorno.

1. Instalar la herramienta de build (solo la primera vez):

   python -m pip install build

2. Generar el paquete wheel desde la raiz del repositorio:

   python -m build --wheel

   Esto crea el archivo dist/mcp_glpi-3.0.0-py3-none-any.whl listo para distribuir.
3. Para instalarlo en otro entorno o servidor, copiar el wheel y ejecutar:

   pip install dist/mcp_glpi-3.0.0-py3-none-any.whl

   Si el archivo esta en otra ubicacion, ajustar la ruta en el comando anterior.

• Logging detallado: pasar --verbose al comando principal para habilitar nivel DEBUG.
• Inspector MCP: pruebe las herramientas disponibles sin cliente externo usando:

  mcp-inspector C:/devIdeas/Repos-propios/mcp-glpi/.venv/Scripts/python.exe "src/mcp_glpi/server.py"

El inspector permite invocar list_tools y call_tool directamente para validar escenarios.

tambien puedes usar un archivo de configuracion

mcp-inspector --config .\examples\config-developer.json

• Sesion GLPI: las herramientas session_validate, profile_list y entity_list permiten validar credenciales y consultar el contexto disponible del usuario autenticado (codigos de perfil/entidad a usar con entity_id/profile_id en el resto de las herramientas).

La suite se ejecuta con pytest y esta localizada en tests/.

# Instalar dependencias de desarrollo opcionales
pip install -e .[dev]

# Ejecutar pruebas con el interprete del entorno virtual
.venv/Scripts/python.exe -m pytest

Las pruebas cubren:

• CommandHandler para uso y validacion de argumentos.
• Helpers de tickets, cambios, sesion y archivos (mcp_glpi.glpi.tickets, mcp_glpi.glpi.changes, mcp_glpi.glpi.session, mcp_glpi.glpi.files).
• El wrapper HTTP de glpi_client (tests/glpi_client/), incluyendo subida/descarga de documentos.
• Validacion basica de claude_desktop_config.json y contenido Markdown.

La capa GLPI fue separada por dominio y responsabilidad:

• src/mcp_glpi/glpi/tickets/: lectura, creacion, actualizacion, comentarios (agregar/listar), soluciones (agregar/listar), asignaciones, enlaces y borrado.
• src/mcp_glpi/glpi/changes/: lectura, creacion, actualizacion, comentarios (agregar/listar), soluciones (agregar/listar), asignaciones, enlaces y borrado.
• src/mcp_glpi/glpi/session/: lectura de sesion, perfiles (listado y cambio de perfil activo) y entidades (listado y cambio de entidad activa) del usuario logueado.
• src/mcp_glpi/glpi/files/: subida (file_upload), descarga (file_download) y vinculo/desvinculo (file_link/file_unlink, itemtype Document_Item) de documentos.
• src/mcp_glpi/glpi/generic.py: acceso generico a itemtypes/subtypes soportados (ITEMTYPE_CATALOG, la lista blanca — incluye Document/Document_Item), detras de item_list/item_get/item_subitem_list/item_type_list/item_subtype_list (solo lectura) e item_delete (la unica mutacion generica).
• src/mcp_glpi/glpi/shared.py: helpers comunes reutilizados por las entidades GLPI, incluyendo fetch_paginated_items/fetch_paginated_subitems (paginacion, apertura de sesion, cambio de entidad/perfil) y EntityList.respond() (dispatch de output/fields) que comparten ticket_list/change_list, los listados de seguimientos/soluciones, e item_list/item_subitem_list.

• Archivo de configuracion: examples/claude_desktop_config.json.
• Variables de entorno soportadas: consulte src/mcp_glpi/common/config.py.

¡Feliz automatizacion con MCP + GLPI!