Zabbix MCP 서버
<!-- mcp-name: io.github.mhajder/zabbix-mcp -->
Zabbix MCP Server는 Zabbix 모니터링 데이터 및 관리 기능에 대한 고급적이고 프로그래밍 가능한 접근을 제공하도록 설계된 Python 기반 Model Context Protocol (MCP) 서버입니다. 이 서버는 호스트, 템플릿, 트리거, 아이템, 문제(problems), 이벤트, 사용자, 프록시, 유지보수 기간 등 Zabbix 리소스를 조회하고 자동화하며 통합하기 위한 최신 API를 노출합니다. 이 서버는 읽기 및 쓰기 작업을 모두 지원하며, 강력한 보안 기능을 갖추고 있어 AI 어시스턴트, 자동화 도구, 대시보드 및 사용자 지정 모니터링 워크플로우와의 통합에 적합합니다.
기능 (Features)
핵심 기능 (Core Features)
- 유연한 필터링을 통해 Zabbix 호스트, 템플릿, 아이템, 트리거 및 호스트 그룹 조회
- 심각도(severity) 필터링을 통한 문제(problems), 이벤트 및 경고 검색
- 모니터링되는 아이템의 기록 및 추세 데이터 접근
- 트리거 상태 및 문제 심각도 모니터링
- 유지보수 기간 및 예정된 다운타임 관리
- 사용자 매크로 및 구성 데이터 조회
- SLA(Service Level Agreement) 및 서비스 정보 가져오기
관리 작업 (Management Operations)
- 호스트, 템플릿 및 호스트 그룹 생성, 업데이트 및 삭제 (활성화된 경우)
- 트리거, 아이템 및 디스커버리 규칙 관리
- 유지보수 기간 및 사용자 매크로 구성
- 모니터링되는 호스트에서 스크립트 실행
- 이벤트 승인(acknowledge) 및 문제 해결
- 사용자 및 프록시 생성 및 관리
- 호스트 및 템플릿에 대한 대량 작업(bulk operations) 지원
고급 기능 (Advanced Capabilities)
- 속도 제한(Rate limiting) 및 API 보안 기능
- 안전한 모니터링을 위해 모든 쓰기 작업을 제한하는 읽기 전용 모드(Read-only mode)
- 대규모 도구 카탈로그를 위한 선택적 tool-search 변환(transform)
- HTTP 전송을 위한 Bearer 토큰 인증
- 포괄적인 로깅 및 감사 추적(audit trails)
- SSL/TLS 지원 및 구성 가능한 타임아웃
- 다중 전송 옵션 (STDIO, SSE, HTTP)
- 오류 추적을 위한 선택적 Sentry 통합
설치 (Installation)
필수 조건 (Prerequisites)
- Python 3.11부터 3.15까지 지원
- Zabbix 서버에 대한 접근이 가능합니다. 버전 6.0부터 7.4까지가 지원되는 범위입니다. 즉,
zabbix-utils 클라이언트가 허용하는 범위이며, ZABBIX_SKIP_VERSION_CHECK=true를 설정하지 않으면 이 범위를 벗어난 연결은 거부됩니다.
- 적절한 권한을 가진 유효한 Zabbix API 토큰 또는 사용자 자격 증명
PyPI에서 빠른 설치
가장 쉽게 시작하는 방법은 PyPI에서 설치하는 것입니다:
서버를 실행하기 전에 Zabbix 인스턴스의 환경 변수를 구성해야 합니다:
export ZABBIX_URL=https://zabbix.example.com/api_jsonrpc.php
export ZABBIX_TOKEN=your-zabbix-api-token
소스에서 설치
- 저장소 클론:
git clone https://github.com/mhajder/zabbix-mcp.git
cd zabbix-mcp
- 의존성 설치:
- 환경 변수 구성:
- 서버 실행:
Docker 사용
배포가 용이하도록 GitHub Packages에 Docker 이미지가 제공됩니다. 이 이미지는 포트 8000의 HTTP Streamable transport를 /mcp 경로로 실행합니다.
docker pull ghcr.io/mhajder/zabbix-mcp:latest
Open WebUI
Open WebUI 0.6.31 이상 버전을 사용하고 이미지에 직접 연결하면 됩니다. 별도의 MCPO 이미지(ghcr.io/mhajder/zabbix-mcpo)는 더 이상 게시되지 않습니다. Open WebUI에서 Admin Settings > Integrations > External Tool Servers로 이동하여, 유형이 **MCP (Streamable HTTP)**인 연결을 URL http://<host>:8000/mcp로 추가하고 Bearer 인증에 MCP_HTTP_BEARER_TOKEN을 설정합니다.
개발 환경 설정
추가 도구와 함께 개발할 경우:
git clone https://github.com/mhajder/zabbix-mcp.git
cd zabbix-mcp
...
구성
환경 변수
사용 가능한 도구
API 정보
api_version: Zabbix API 버전 정보를 가져옵니다.
호스트 관리
host_get: 그룹, 템플릿, 프록시 및 검색 기준에 따라 필터링할 수 있는 호스트 목록을 나열합니다.host_create: 인터페이스와 템플릿 연결을 포함하여 새 호스트를 생성합니다.host_update: 호스트 속성(이름, 상태, 설명)을 업데이트합니다.host_delete: ID별로 호스트를 삭제합니다.
호스트 그룹 관리
hostgroup_get: 필터링할 수 있는 호스트 그룹 목록을 나열합니다.hostgroup_create: 새 호스트 그룹을 생성합니다.hostgroup_update: 기존 호스트 그룹의 속성(이름)을 업데이트합니다.hostgroup_delete: 호스트 그룹을 삭제합니다.
템플릿 관리
template_get: 필터링할 수 있는 템플릿 목록을 나열합니다.template_create: 새 템플릿을 생성합니다.template_update: 템플릿 속성(이름, 설명)을 업데이트합니다.template_delete: 템플릿을 삭제합니다.
아이템 관리
item_get: 호스트, 그룹, 템플릿별로 필터링할 수 있는 아이템 목록을 나열합니다.item_create: 호스트에 새 아이템을 생성합니다.item_update: 아이템 속성(이름, 지연 시간, 단위, 설명, 상태)을 업데이트합니다.item_delete: 아이템을 삭제합니다.
트리거 관리
trigger_get: 심각도 및 상태 필터링을 통해 트리거 목록을 나열합니다.trigger_create: 표현식과 함께 새 트리거를 생성합니다.trigger_update: 트리거 속성(설명, 표현식, 우선순위, 상태, 댓글)을 업데이트합니다.trigger_delete: 트리거를 삭제합니다.
문제 및 이벤트 관리
problem_get: 심각도 및 시간 필터링을 통해 현재 문제를 가져옵니다.event_get: 시간 범위 필터링을 통해 이벤트를 가져옵니다.event_acknowledge: 선택적 메시지와 함께 이벤트를 확인(Acknowledge)합니다.
기록 및 추세
history_get: 아이템에 대한 과거 데이터를 가져옵니다.trend_get: 아이템에 대한 추세 데이터를 가져옵니다.
사용자 관리
(내용 없음)
사용자 관리 (User Management)
user_get: 선택적 필터링이 가능한 사용자 목록 조회user_create: 새 사용자 생성user_update: 사용자 속성 업데이트 (이름, 성, 비밀번호, 유형)user_delete: 사용자 삭제
프록시 관리 (Proxy Management)
proxy_get: 선택적 필터링이 가능한 프록시 목록 조회proxy_create: 새 프록시 생성proxy_update: 프록시 속성 업데이트 (이름, 운영 모드, 설명)proxy_delete: 프록시 삭제
유지보수 관리 (Maintenance Management)
maintenance_get: 유지보수 기간 목록 조회maintenance_create: 새 유지보수 기간 생성maintenance_update: 유지보수 기간 속성 업데이트 (이름, 시간, 설명)maintenance_delete: 유지보수 기간 삭제
action_get: 액션 목록 조회 (트리거, 자동 등록 등)mediatype_get: 미디어 유형 목록 조회
그래프 및 디스커버리 (Graph & Discovery)
graph_get: 선택적 필터링이 가능한 그래프 목록 조회discoveryrule_get: LLD(Low Level Discovery) 디스커버리 규칙 목록 조회drule_get: 네트워크 디스커버리 규칙 목록 조회itemprototype_get: 디스커버리 규칙에서 아이템 프로토타입 가져오기
SLA 및 서비스 (SLA & Services)
sla_get: SLA(Service Level Agreement) 목록 조회service_get: 서비스 목록 조회
스크립트 (Scripts)
script_get: 스크립트 목록 조회script_execute: 호스트에서 스크립트 실행
사용자 매크로 (User Macros)
usermacro_get: 사용자 매크로 목록 조회 (호스트 및 전역)usermacro_create: 호스트 매크로 생성usermacro_delete: 호스트 매크로 삭제
구성 관리 (Configuration Management)
configuration_export: Zabbix 구성을 JSON 또는 XML로 내보내기(Export)configuration_import: JSON 또는 XML에서 Zabbix 구성 가져오기(Import)
보안 및 안전 기능 (Security & Safety Features)
읽기 전용 모드 (Read-Only Mode)
서버는 모든 쓰기 작업을 비활성화하여 안전한 모니터링을 지원하는 읽기 전용 모드를 지원합니다:
비활성화할 특정 카테고리의 도구를 설정된 태그를 통해 비활성화할 수 있습니다:
DISABLED_TAGS=alert,bills
FastMCP 도구 검색은 많은 도구를 가진 서버의 프롬프트 크기를 줄일 수 있습니다.
활성화하면 list_tools가 두 개의 합성(synthetic) 도구를 반환합니다:
search_tools: 일치하는 도구를 찾아 전체 스키마를 반환합니다.call_tool: 이름으로 발견된 모든 도구를 실행합니다.
다음과 같이 활성화할 수 있습니다:
TOOL_SEARCH_ENABLED=true
TOOL_SEARCH_STRATEGY=bm25 # bm25 또는 regex
TOOL_SEARCH_MAX_RESULTS=8 # 선택 사항, 기본값은 5
bm25는 자연어 질의를 지원하며, regex는 결정론적 매칭을 위해 pattern 입력을 사용합니다.
도구 검색은 기존 가시성 제어(읽기 전용 모드 및 비활성화된 태그)를 존중합니다.
속도 제한 (Rate Limiting)
서버는 API 사용량을 제어하고 오용을 방지하기 위해 속도 제한을 지원합니다. 활성화되면, 슬라이딩 윈도우 알고리즘(sliding window algorithm)을 사용하여 클라이언트별로 요청이 제한됩니다.
다음 환경 변수를 .env 파일에 설정하여 속도 제한을 활성화할 수 있습니다:
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=60 # 윈도우당 허용 최대 요청 수 (기본값: 60)
RATE_LIMIT_WINDOW_MINUTES=1 # 분 단위 윈도우 크기
RATE_LIMIT_ENABLED가 true로 설정되면, 서버는 속도 제한 미들웨어를 적용합니다. 환경에 맞게 RATE_LIMIT_MAX_REQUESTS와 RATE_LIMIT_WINDOW_MINUTES를 조정하십시오.
Sentry 오류 추적 및 모니터링 (선택 사항)
서버는 오류 추적, 성능 모니터링 및 디버깅을 위해 선택적으로 Sentry를 지원합니다. Sentry 통합은 완전히 선택 사항이며 구성된 경우에만 초기화됩니다.
설치
Sentry 모니터링을 활성화하려면 다음 선택적 종속성을 설치하십시오:
구성
.env 파일에 SENTRY_DSN 환경 변수를 설정하여 Sentry를 활성화합니다:
기능
활성화되면, Sentry는 다음을 자동으로 캡처합니다:
- 예외 및 오류 (Exceptions & Errors): 전체 컨텍스트를 포함한 모든 미처리 예외
- 성능 지표 (Performance Metrics): 요청/응답 시간 및 추적 기록
- MCP 통합 (MCP Integration): 상세한 MCP 서버 활동 및 상호 작용
- 로그 및 이동 경로 (Logs & Breadcrumbs): 디버깅을 위한 애플리케이션 로그 및 이벤트 흔적
- 컨텍스트 데이터 (Context Data): 환경, 클라이언트 정보 및 요청 매개변수
Sentry DSN 받기
- sentry.io에서 무료 계정 생성
- 새로운 Python 프로젝트 생성
- 프로젝트 설정에서 DSN 복사
.env 파일에 설정
Sentry 비활성화
Sentry는 완전히 선택 사항입니다. SENTRY_DSN을 설정하지 않으면, 서버는 어떤 Sentry 통합 없이 정상적으로 실행되며 모니터링 데이터가 수집되지 않습니다.
SSL/TLS 구성
서버는 SSL 인증서 검증 및 사용자 지정 타임아웃 설정을 지원합니다:
ZABBIX_VERIFY_SSL=true # SSL 인증서 검증 활성화
ZABBIX_TIMEOUT=30 # 초 단위 연결 타임아웃
전송 구성 (Transport Configuration)
서버는 MCP 프로토콜을 위한 여러 전송 메커니즘을 지원합니다:
STDIO 전송 (기본값)
기본 전송 방식은 통신에 표준 입/출력(stdin/stdout)을 사용합니다. 이는 로컬 사용 및 stdin/stdout을 통해 통신하는 도구와의 통합에 이상적입니다:
HTTP SSE 전송 (Server-Sent Events)
네트워크 기반 배포의 경우, Server-Sent Events(SSE)를 사용하여 HTTP로 사용할 수 있습니다. 이를 통해 MCP 서버에 실시간 스트리밍과 함께 HTTP로 접근할 수 있습니다:
MCP_TRANSPORT=sse
MCP_HTTP_HOST=127.0.0.1 # 로컬호스트
MCP_HTTP_PORT=8000 # 리스닝 포트
...
Bearer 토큰과 함께 SSE 전송을 사용하는 경우, 클라이언트는 요청에 해당 토큰을 포함해야 합니다:
curl -H
HTTP Streamable 전송 방식은 요청/응답 스트리밍을 지원하는 HTTP 기반 통신을 제공합니다. 이는 웹 통합 및 HTTP 엔드포인트가 필요한 도구에 이상적입니다:
```env
MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=8000
...
Bearer 토큰을 사용하여 스트리밍 가능한 전송 방식을 사용할 때:
curl -H "Authorization: Bearer your-secret-token" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
...
참고: HTTP 전송 방식은 jsonrpc 및 id 필드를 사용한 적절한 JSON-RPC 형식이 필요합니다. 또한 서버는 일부 작업을 위해 세션 초기화를 요구할 수도 있습니다.
Health Endpoint (상태 확인 엔드포인트)
HTTP 전송 방식(sse와 http) 모두 GET /health를 제공하며, 이는 서버가 요청을 처리하고 있을 때 200 ok 응답을 반환합니다. 이 기능은 Bearer 토큰이 필요하지 않으며 Zabbix에 접속하지 않으므로, Zabbix 장애가 MCP 서버의 비정상 상태로 표시되지 않습니다. Docker 이미지의 HEALTHCHECK는 이를 사용합니다:
curl http://localhost:8000/health
FastMCP 전송 방식에 대한 자세한 정보는 FastMCP 문서를 참조하십시오.
기여 (Contributing)