prtg-mcp

PRTG Network Monitor(Paessler 네트워크/인프라 모니터링)용 MCP 서버입니다. PRTG의 네이티브 HTTP API의 센서, 디바이스, 과거 센서 데이터를 MCP 도구로 노출합니다.

개요

• 무상태(stateless) HTTP 서비스입니다. 자격 증명이 영구 저장되지 않으며, 각 요청이 헤더를 통해 자체 자격 증명을 제공하고 해당 단일 요청의 수명 동안만 사용됩니다.

• 동시 요청을 지원하며, 요청별 자격 증명 격리는 전역/공유 클라이언트 인스턴스가 아닌 Python contextvars로 수행됩니다.

• 진입점: POST /mcp(MCP 프로토콜) 및 GET /health(헬스 체크).

• 기본 포트: 8080(MCP_HTTP_PORT로 구성 가능).

Related MCP server: mcp-ntopng

인증

이 프로그램의 대부분의 통합과 달리 PRTG에는 별도의 로그인이나 토큰 교환이 없습니다. 사용자 이름과 "passhash"(PRTG UI의 My Account -> API Key에서 생성되며, 실제 계정 비밀번호가 아님)가 모든 호출에서 일반 쿼리 매개변수로 전송됩니다. 따라서 캐시할 것이 없으며, 각 호출은 이미 벤더 설계상 완전히 자체 포함적이고 무상태입니다.

HEADER 인증 매개변수 설명

헤더가 하나라도 없으면 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": []
}

잘못된 자격 증명은 도구 수준 오류 봉투(아래 오류 봉투 참조)로 표시되며, PRTG의 HTTP 상태 코드에서 분류됩니다. 401/403은 unauthorized로 매핑됩니다. 2xx가 아닌 응답이 오면 이 서버는 JSON 본문에서 message/error 필드를 추출하려 시도하고, 해당 본문이 JSON이 아닌 경우(PRTG는 특정 잘못된 요청에 대해 .json 엔드포인트에서도 XML <error> 본문으로 대체할 수 있음) 원시 응답 텍스트로 대체합니다.

환경 변수

MCP 엔드포인트

• POST /mcp — MCP 프로토콜(스트리밍 가능한 HTTP 전송)

• GET /health — 헬스 체크, {"status": "ok"} 반환(순수 로컬 프로브, PRTG 호출 안 함)

도구 목록

3개 도구 모두 읽기 전용(readOnlyHint=True, idempotentHint=True)이며, 이 서비스에는 쓰기/삭제 도구가 없습니다.

count는 PRTG의 table.json 엔드포인트에 대해 벤더 측 문서화된 하드 상한이 없으므로, 이 서버는 값을 검증 없이 그대로 전달하는 대신 플랫폼 자체의 폴백 상한을 적용합니다. 기본값은 50이며, 200을 초과하는 값은 PRTG에 그대로 전송되지 않고 200으로 자동으로 조정됩니다.

응답 형식

이 서버가 호출하는 두 엔드포인트(table.json, historicdata.json)는 모두 벤더의 JSON 접미사 변형이므로, 성공 시 클라이언트는 항상 JSON만 파싱합니다. PRTG의 HTTP API는 원칙적으로 다른 엔드포인트/매개변수에 대해 XML을 반환할 수 있으므로, 클라이언트는 방어적으로 파싱합니다. 2xx가 아닌 응답은 아래의 구조화된 오류 봉투로 분류되고, 2xx 응답이 JSON으로 파싱에 실패하면 예외를 발생시키는 대신 원시 텍스트가 raw_response 키 아래에 반환됩니다.

오류 봉투

도구 오류는 발생된 예외 대신 구조화된 JSON 문자열로 반환되므로, 호출 에이전트가 code를 기준으로 분기하여 재시도 여부를 결정할 수 있습니다:

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

code는 not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error 중 하나입니다. 빈 결과 집합은 not_found가 아닌 일반(비오류) 빈 컬렉션으로 반환됩니다.

도구 반환 값(성공 및 오류 모두)은 20,000자로 제한된 컴팩트 JSON(ensure_ascii=False, indent 없음)입니다. 크기가 초과된 결과는 가장 큰 목록 필드를 잘라내고 무제한 블롭을 반환하는 대신 truncated/original_count를 보고합니다.

테스트 예시

# 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": {}
    }
  }'

실제 검증됨(2026-07-30): 실제 PRTG 코어 서버를 대상으로 실행 중인 이 서버를 통해 실제 자격 증명으로 3개 도구를 모두 종단 간 호출했습니다. prtg_get_sensors와 prtg_get_devices는 모두 실제 prtg-version 문자열과 유효한(빈) 결과 집합과 함께 200을 반환했습니다. 이 특정 테스트 계정은 가시 범위 내에 센서/디바이스가 0개 프로비저닝되어 있으며, 동일한 자격 증명으로 content=probes를 별도로 쿼리하여 실제 데이터(PRTG Root probe와 여러 실제 스케줄링 객체)를 반환함으로써 인증 실패가 아닌 진정한 "데이터 없음" 상태임을 확인했습니다. prtg_get_sensor_historic_data는 실제 센서 ID가 없었으므로(참조할 실제 센서 ID가 없음) 비센서 객체 ID로 호출했으며, API에 정상적으로 도달하여 벤더 자체의 콘텐츠 수준 오류("The selected object cannot be used here")를 반환하여 요청/인증 파이프라인이 올바르게 연결되어 있음을 입증했습니다.

API 참조

• 공개, 로그인 불필요:

  • 센서/디바이스 테이블 형식: https://www.paessler.com/manuals/prtg/multiple_object_property_or_status#supported_output

  • 과거 데이터: https://www.paessler.com/manuals/prtg/historic_data

알려진 격차

• 범위는 정확히 MSPbots의 구성된 3개 엔드포인트이며, 벤더의 전체 API 표면이 아닙니다 — PRTG의 API는 실시간 센서 제어(일시 중지/재개/확인), 객체 생성/삭제, 알림, 보고서 등을 포함하지만, 이는 여기서 범위 밖입니다.

• 센서/디바이스 데이터를 실제 레코드로 시연할 수 없었습니다 — 제공된 테스트 계정(Dash_Display, 대시보드 전용 표시 계정으로 추정)은 이 특정 PRTG 인스턴스의 가시 범위에 센서 0개와 디바이스 0개가 프로비저닝되어 있습니다. 실시간 테스트에서 동일한 자격 증명으로 항상 채워진 다른 객체 유형(content=probes)을 성공적으로 쿼리하고 실제 데이터를 받아 진정한 빈 결과(인증 또는 구현 버그가 아님)임을 확인했습니다.

• prtg_get_sensor_historic_data는 실제 센서 ID로 테스트할 수 없었습니다 같은 이유(참조할 센서가 없음)이며, 대신 잘못된 객체 ID에 대한 벤더 자체의 콘텐츠 수준 오류 응답을 확인하여 요청 형식과 인증이 올바른지 검증했습니다.