prtg-mcp

Servidor MCP para PRTG Network Monitor (monitoreo de red/infraestructura de Paessler). Expone los sensores, dispositivos y datos históricos de sensores de la API HTTP nativa de PRTG como herramientas MCP.

Descripción general

• Servicio HTTP sin estado. Nunca se guardan credenciales: cada solicitud proporciona sus propias credenciales mediante cabeceras, que se usan solo durante la vida de esa solicitud.

• Admite solicitudes concurrentes; el aislamiento de credenciales por solicitud se realiza mediante contextvars de Python, no con una instancia de cliente global/compartida.

• Puntos de entrada: POST /mcp (protocolo MCP) y GET /health (comprobación de estado).

• Puerto predeterminado: 8080 (configurable mediante MCP_HTTP_PORT).

Related MCP server: mcp-ntopng

Autenticación

A diferencia de la mayoría de las integraciones en este programa, PRTG no tiene un inicio de sesión o intercambio de tokens separado: el nombre de usuario y un "passhash" (generado en la interfaz de PRTG en Mi cuenta -> Clave API, no la contraseña literal de la cuenta) se envían como parámetros de consulta en cada llamada. Por lo tanto, no hay nada que almacenar en caché: cada llamada ya es completamente autónoma y sin estado por diseño del propio proveedor.

Parámetros de autorización de cabecera

Si falta alguna cabecera, se devuelve 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-PRTG-Server-Url, X-PRTG-Username, and X-PRTG-Passhash headers",
  "required_headers": ["X-PRTG-Server-Url", "X-PRTG-Username", "X-PRTG-Passhash"],
  "optional_headers": []
}

Una credencial no válida se manifiesta como un sobre de error a nivel de herramienta (consulte Sobre de error a continuación), clasificado a partir del código de estado HTTP de PRTG: un 401/403 se asigna a unauthorized. Ante cualquier respuesta que no sea 2xx, este servidor intenta extraer un campo message/error del cuerpo JSON y, si el cuerpo no es JSON, recurre al texto de respuesta sin procesar (PRTG puede, para ciertas solicitudes mal formadas, devolver un cuerpo XML <error> incluso en el endpoint .json).

Variables de entorno

Endpoint MCP

• POST /mcp — protocolo MCP (transporte HTTP transmisible)

• GET /health — comprobación de estado, devuelve {"status": "ok"} (sonda puramente local, no llama a PRTG)

Lista de herramientas

Las 3 herramientas son de solo lectura (readOnlyHint=True, idempotentHint=True); no hay herramientas de escritura/eliminación en este servicio.

count no tiene un máximo estricto documentado por el proveedor para el endpoint table.json de PRTG, por lo que este servidor aplica el límite máximo de reserva de la plataforma en lugar de pasar los valores sin verificar: predeterminado 50, los valores superiores a 200 se reducen silenciosamente a 200 en lugar de enviarse a PRTG tal cual.

Formato de respuesta

Ambos endpoints a los que llama este servidor (table.json, historicdata.json) son las variantes con sufijo JSON del proveedor, por lo que, en caso de éxito, el cliente solo analiza JSON. La API HTTP de PRTG puede, en principio, devolver XML para otros endpoints/parámetros, por lo que el cliente analiza de forma defensiva: una respuesta que no sea 2xx se clasifica en el sobre de error estructurado a continuación, y si una respuesta 2xx no se puede analizar como JSON, su texto sin procesar se devuelve bajo una clave raw_response en lugar de lanzar una excepción.

Sobre de error

Los errores de herramienta se devuelven como una cadena JSON estructurada en lugar de una excepción lanzada, para que el agente que llama pueda ramificar según code y decidir si reintentar:

{"error": {"code": "upstream_error", "message": "...", "retryable": true}}

code es uno de: not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error. Los conjuntos de resultados vacíos se devuelven como una colección vacía normal (sin error), no como not_found.

Los valores de retorno de las herramientas (tanto de éxito como de error) son JSON compacto (ensure_ascii=False, sin indent) con un máximo de 20 000 caracteres: un resultado sobredimensionado trunca su campo de lista más grande e informa truncated/original_count en lugar de devolver un blob ilimitado.

Ejemplo de prueba

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-PRTG-Server-Url: prtg.example.com" \
  -H "X-PRTG-Username: api_user" \
  -H "X-PRTG-Passhash: <your-passhash>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "prtg_get_sensors",
      "arguments": {}
    }
  }'

Verificado en vivo (2026-07-30) contra un servidor PRTG real, las 3 herramientas se llamaron de extremo a extremo a través de este servidor en ejecución con credenciales reales: prtg_get_sensors y prtg_get_devices devolvieron 200 con una cadena prtg-version real y un conjunto de resultados válido (vacío): esta cuenta de prueba en particular no tiene sensores/dispositivos aprovisionados en su ámbito visible, confirmado como una condición genuina de "sin datos" (no un error de autenticación) al consultar por separado content=probes, que devolvió datos reales (la sonda raíz de PRTG y varios objetos de programación reales) con las mismas credenciales. prtg_get_sensor_historic_data, llamada con un ID de objeto que no es de sensor (ya que no había un ID de sensor real disponible), llegó correctamente a la API y devolvió el error a nivel de contenido del propio proveedor ("El objeto seleccionado no se puede usar aquí"), lo que demuestra que la canalización de solicitud/autenticación está correctamente configurada.

Referencia de la API

• Público, sin necesidad de inicio de sesión:

  • Formato de tabla de sensores/dispositivos: https://www.paessler.com/manuals/prtg/multiple_object_property_or_status#supported_output

  • Datos históricos: https://www.paessler.com/manuals/prtg/historic_data

Limitaciones conocidas

• El alcance es exactamente los 3 endpoints configurados de MSPbots, no la superficie completa de la API del proveedor — la API de PRTG también cubre el control de sensores en vivo (pausar/reanudar/reconocer), creación/eliminación de objetos, notificaciones, informes y más; eso queda fuera del alcance aquí.

• Los datos de sensores/dispositivos no se pudieron demostrar con registros reales — la cuenta de prueba proporcionada (Dash_Display, probablemente una cuenta de visualización solo de panel) no tiene sensores ni dispositivos aprovisionados en su ámbito visible en esta instancia de PRTG. Las pruebas en vivo confirmaron que se trata de un resultado vacío genuino (no un error de autenticación o implementación) al consultar con éxito un tipo de objeto diferente y siempre poblado (content=probes) con las mismas credenciales y obtener datos reales.

• prtg_get_sensor_historic_data no se pudo probar con un ID de sensor real por la misma razón (no hay sensores para referenciar); en su lugar, se verificó confirmando la respuesta de error a nivel de contenido del propio proveedor para un ID de objeto no válido, lo que demuestra que el formato de solicitud y la autenticación son correctos.