Zabbix Investigation MCP

Zabbix API의 읽기 전용 데이터를 n8n AI Agent에 제공하는 독립 MCP 서버입니다. Agent가 조사할 호스트·메트릭·시간 범위·집계 간격을 결정하고, 이 서버는 입력 검증과 Zabbix 조회, 수치 집계를 결정론적으로 수행합니다.

제공 도구

• find_hosts
• get_incident_events
• get_trigger_details
• list_relevant_metrics
• get_metric_summary
• get_metric_history
• get_related_events

Zabbix 설정 변경, 이벤트 확인 처리, 스크립트 및 원격 명령 실행 도구는 제공하지 않습니다.

환경 변수

Copy-Item .env.example .env

필수 설정:

• ZABBIX_URL: /api_jsonrpc.php를 포함한 Zabbix API URL
• ZABBIX_API_TOKEN: 읽기 전용 API Token
• ZABBIX_ALLOWED_HOST_GROUP_IDS: 조회를 허용할 Host Group ID 목록. 비워 두면 토큰이 볼 수 있는 모든 호스트가 조사 대상이 됩니다. 제한은 그룹 단위로만 동작하므로, 특정 호스트 몇 대만 대상으로 삼으려면 Zabbix에 전용 호스트 그룹을 만들어 그 ID 하나만 지정하십시오. 기존 운영 그룹을 그대로 쓰면 의도하지 않은 호스트까지 함께 열립니다.
• ZABBIX_MCP_AUTH_TOKEN: MCP 클라이언트가 사용할 Bearer Token

ZABBIX_MCP_AUTH_TOKEN은 길고 무작위인 값을 사용합니다.

[Convert]::ToHexString(
  [Security.Cryptography.RandomNumberGenerator]::GetBytes(32)
).ToLower()

Docker 실행

docker compose up -d --build
docker compose ps
Invoke-RestMethod http://127.0.0.1:3000/healthz

기본 엔드포인트:

• MCP: http://<instance-a>:3000/mcp
• 상태 확인: http://<instance-a>:3000/healthz

MCP 요청에는 다음 헤더가 필요합니다.

Authorization: Bearer <ZABBIX_MCP_AUTH_TOKEN>

네트워크 노출 제한

컨테이너 포트가 게시되는 호스트 인터페이스는 MCP_BIND_ADDRESS가 정합니다.

MCP_BIND_ADDRESS=192.168.20.22   # 이 머신의 사설 IP

값을 지정하지 않으면 127.0.0.1로 게시되므로, 설정을 빠뜨려도 공인 인터페이스에 열리지 않습니다.

MCP_HOST와 혼동하지 않아야 합니다. MCP_HOST는 프로세스 자체의 바인드 주소이고 docker compose에서는 컨테이너 내부 기준 0.0.0.0으로 고정됩니다. 호스트 노출을 실제로 통제하는 값은 MCP_BIND_ADDRESS입니다.

Docker는 자신의 forwarding 규칙을 ufw보다 앞에 삽입하므로, 0.0.0.0으로 게시한 포트는 호스트 방화벽으로 막히지 않습니다. 방화벽에 의존하지 말고 바인드 주소를 지정하십시오. 클라우드 보안 그룹에서도 3000 포트를 사설 대역으로 제한하는 것을 권장합니다.

적용 결과는 실행 전에 확인할 수 있습니다.

docker compose config

ports:
  - host_ip: 192.168.20.22
    published: "3000"
    target: 3000

MCP_ALLOWED_HOSTS는 소스 IP가 아니라 요청의 Host 헤더를 검사합니다. DNS rebinding 방어용이며 네트워크 접근 제어를 대신하지 않습니다.

운영 환경에서는 3000 포트를 인터넷에 그대로 공개하지 말고 HTTPS reverse proxy, 방화벽 또는 사설 네트워크를 사용합니다.

로컬 개발

요구 사항은 Node.js 20 이상입니다.

npm ci
npm run typecheck
npm test
npm run build
npm run dev

실제 Zabbix 통합 테스트

tests/integration/은 실제 Zabbix API에 붙어 7개 도구와 정책 가드레일을 검증합니다. 환경 변수가 없으면 자동으로 건너뛰므로 npm test와 CI는 Zabbix 없이도 그대로 통과합니다.

Zabbix가 사설망에 있으면 먼저 터널을 엽니다.

ssh -N -L 8081:<zabbix-host>:80 <jump-host>

$env:ZABBIX_INTEGRATION_URL = "http://127.0.0.1:8081/zabbix/api_jsonrpc.php"
$env:ZABBIX_INTEGRATION_HOST = "<조사할 호스트 이름>"
npm run test:integration

• ZABBIX_API_TOKEN은 지정하지 않으면 저장소 .env에서 읽습니다. 토큰을 명령줄에 노출하지 않아도 됩니다.
• 세 변수(ZABBIX_INTEGRATION_URL, ZABBIX_API_TOKEN, ZABBIX_INTEGRATION_HOST)가 모두 있어야 실행됩니다.
• 대상 호스트에 이벤트가 없으면 이벤트 관련 단정은 건너뛰고, 나머지 계약과 가드레일은 그대로 검증합니다.

토큰에는 최소 권한으로 다음 6개 메서드만 허용하면 충분합니다.

host.get  event.get  trigger.get  item.get  history.get  trend.get

집계 정책

• 짧은 범위는 history.get 원시 값을 지정 간격으로 집계합니다.
• 오래된 장기 범위는 trend.get 결과를 재집계합니다.
• 결과에 data_source, sample_count, coverage_ratio, partial을 포함합니다.
• 장기 조회는 최소 1시간 집계만 허용합니다.
• LLM은 평균·최댓값을 계산하지 않고 MCP가 반환한 값을 해석합니다.

partial은 다음 중 하나라도 해당하면 true입니다.

• 조회 한도(INVESTIGATION_MAX_SOURCE_POINTS)에 도달해 원본이 잘렸을 때
• 출력 한도(INVESTIGATION_MAX_HISTORY_POINTS)에 도달해 응답이 잘렸을 때
• coverage_ratio가 INVESTIGATION_MIN_COVERAGE_RATIO(기본 0.95) 미만일 때

세 번째 조건 때문에, 아무것도 잘리지 않았더라도 요청 구간의 상당 부분에 원본 데이터가 없으면 완전한 응답으로 표시하지 않습니다. 예를 들어 보존 기간이 짧은 아이템을 7일 구간으로 조회하면 coverage_ratio가 낮게 나오고 partial=true가 됩니다. RCA Writer는 이를 보고서 limitations에 반영해야 합니다.

저장소 구조

.
├── src/
├── tests/
├── Dockerfile
├── docker-compose.yml
├── package.json
└── .env.example

클라이언트의 ZABBIX_MCP_URL은 이 서버의 /mcp 주소를 가리켜야 하며, n8n HTTP Bearer Auth credential에는 동일한 ZABBIX_MCP_AUTH_TOKEN을 입력합니다.