Servidor MCP de i-net HelpDesk

Un servidor MCP que proporciona la API web de tickets de i-net HelpDesk como herramientas para cualquier agente de IA: buscar y leer tickets, ver pasos de procesamiento, crear nuevos tickets y ejecutar acciones en tickets (responder, cerrar, escalar…) incluyendo archivos adjuntos.

El servidor se puede operar de dos maneras:

Requisitos previos

• Python 3.10 o superior

• Un i-net HelpDesk con la API web activada

• Un usuario con el permiso "Web API" — sin este permiso el servidor responde con HTTP 403. Los tickets visibles y las acciones permitidas dependen de los roles de ese usuario.

Related MCP server: tickiti-mcp

Instalación

# direkt aus dem Repository ausführen (empfohlen für den Einstieg)
uvx --from git+https://github.com/roddyst/i-net_mcp_server inet-helpdesk-mcp --help

# oder klassisch installieren
pip install git+https://github.com/roddyst/i-net_mcp_server

Para el desarrollo:

git clone https://github.com/roddyst/i-net_mcp_server
cd i-net_mcp_server
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest

Inicio rápido: stdio (agente local)

export INET_BASE_URL="https://helpdesk.example.com:9000"
export INET_TOKEN="VGhpcyBpcyBqdXN0IGEgZGVtbyBhY2Nlc3MgdG9rZW4u"
inet-helpdesk-mcp

Configuración para Claude Desktop / Claude Code (claude_desktop_config.json o .mcp.json) — más ejemplos en examples/:

{
  "mcpServers": {
    "i-net-helpdesk": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/roddyst/i-net_mcp_server", "inet-helpdesk-mcp"],
      "env": {
        "INET_BASE_URL": "https://helpdesk.example.com:9000",
        "INET_TOKEN": "dein-access-token"
      }
    }
  }
}

En lugar de un token, también funcionan INET_USERNAME e INET_PASSWORD (Basic Auth). El token se envía como Authorization: Bearer <token>, exactamente como se describe en la documentación de i-net.

Inicio rápido: HTTP (alojado centralmente)

inet-helpdesk-mcp --transport http --host 0.0.0.0 --port 8000 \
                  --base-url https://helpdesk.example.com:9000

El endpoint está en http://<host>:8000/mcp. El agente ingresa esta URL y envía su token de HelpDesk en el encabezado Authorization — ese es exactamente el flujo "URL + Bearer Token", el servidor reenvía el encabezado al HelpDesk. Ejemplo para un cliente MCP que admite servidores remotos:

{
  "mcpServers": {
    "i-net-helpdesk": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer dein-access-token" }
    }
  }
}

Sin --base-url, el cliente determina además el sistema de destino a través del encabezado X-Inet-Base-Url. Esto es práctico para inquilinos con varias instancias de HelpDesk, pero abre el servidor como proxy para direcciones arbitrarias — por lo tanto, en una red abierta es mejor establecer un --base-url fijo (entonces el encabezado está desactivado, a menos que se permita con --allow-url-header).

Nota sobre la operación: El servidor no termina TLS por sí mismo ni autentica clientes de forma independiente — el inicio de sesión se realiza en el HelpDesk con el token reenviado. Si debe ser accesible más allá de la red local, se necesita un proxy inverso con HTTPS delante.

Herramientas

create_ticket y apply_ticket_action no se registran en absoluto con --read-only — útil si un agente solo debe poder leer.

Los IDs de ticket se aceptan tanto como número como en la forma codificada que aparece en las líneas de asunto de los correos de HelpDesk.

Flujo típico

1. search_tickets con una frase como Impresora o Resource:"First Level Support"

2. get_ticket / list_ticket_steps / get_ticket_step para leer

3. list_ticket_actions para determinar la action_id válida

4. apply_ticket_action con esa ID — las IDs difieren según ticket, usuario y estado del ticket, por lo que no se deben adivinar.

Campos de ticket y argumentos de acción

ticket_fields, step_fields y action_arguments son opcionales y normalmente no se necesitan. Si se usan, se aplican las reglas de la API web: las claves deben corresponder a claves de campo reales (o su nombre visible localizado), los valores son cadenas; los valores JSON deben codificarse como cadena. Ejemplos de la documentación de i-net:

{
  "ticketextension.dispatchNow": "ALWAYS",           // Ticket sofort disponieren
  "ticketextension.automail": "NO_MAILS_TO_ENDUSER", // keine Auto-Mails an Endanwender
  "processingtimeextension.appointment": "1733875200000", // Wiedervorlage/Termin
  "ticketactionextension.escalate": "{'targetResID':'<GUID>','changeTicketStatus':true}"
}

Los campos de ticket desconocidos generan un error, los argumentos de acción desconocidos son descartados silenciosamente por HelpDesk y solo se escriben en el registro de depuración.

Archivos adjuntos

Los archivos adjuntos se pasan como una lista, cada uno con contenido ya sea en línea como Base64 o como ruta en el sistema de archivos del servidor:

{
  "text": "Anfrage mit Anhang",
  "attachments": [
    { "name": "screenshot.png", "content_base64": "iVBORw0KGgo…" },
    { "path": "/tmp/protokoll.pdf", "attachment_type": "Attachment" }
  ]
}

path funciona solo en modo stdio, donde el agente y el servidor comparten la misma máquina; en los modos HTTP está automáticamente desactivado (y se puede deshabilitar también para stdio con --no-local-files). Valores permitidos para attachment_type: Attachment, EmbeddedImage, Signature, Unknown. Límite superior por archivo: 25 MB.

Configuración

Cada opción existe como variable de entorno y como conmutador de línea de comandos; la línea de comandos gana.

Solución de problemas

• Llamar primero a server_info — muestra la URL base, el método de autenticación y si una consulta de prueba contra el HelpDesk funciona.

• HTTP 401/403: Token expirado o al usuario le falta el permiso "Web API".

• HTTP 404 en un ticket: El ticket no existe o no es visible para este usuario; los tickets aún no autorizados necesitan el rol de despachador.

• Errores de conexión: Verificar la URL base incluyendo el puerto (el valor predeterminado de HelpDesk es 9000). Con sistemas de prueba autofirmados ayuda --no-verify-tls.

• Más detalles con --log-level DEBUG (los registros van a stderr).

Avisos de seguridad

• Las credenciales están en variables de entorno o en el encabezado Authorization y nunca se registran.

• El servidor hace exactamente lo que el usuario conectado puede hacer: la verificación de permisos permanece en el HelpDesk.

• apply_ticket_action y create_ticket modifican datos y pueden, según la configuración, enviar correos electrónicos a los usuarios finales. Para pruebas se recomienda el argumento de acción "ticketextension.automail": "NEVER" o un sistema de prueba.

• get_ticket devuelve de forma predeterminada todos los campos de un ticket, incluidos los datos personales: limitar específicamente con fields.

Resumen en inglés

MCP server exposing the i-net HelpDesk Ticket Web-API: search, read, create and act on tickets, with attachment support. Run it over stdio (credentials from INET_BASE_URL + INET_TOKEN) or over streamable HTTP, where each client authenticates by sending its own Authorization: Bearer <token> header — and, when no base URL is configured, selects the HelpDesk instance with an X-Inet-Base-Url header. Tools: server_info, search_tickets, get_ticket, list_ticket_actions, list_ticket_steps, get_ticket_step, create_ticket, apply_ticket_action. Start with --read-only to expose the reading tools only.

Licencia

MIT. No es un producto oficial de i-net software GmbH. Documentación de la API web: https://docs.inetsoftware.de/helpdesk/help/webapi.ticket/p/ticket-web-api