Zabbix MCP Server
Zabbix API와 연결하여 현재 발생 중인 문제(Problems)와 트리거(Triggers) 정보를 조회하는 MCP(Model Context Protocol) 서버입니다.
기능
list_problems: 현재 발생 중인 Zabbix 문제 목록 조회
list_triggers: 현재 활성화된 Zabbix 트리거 목록 조회
zabbix_health: Zabbix API 연결 상태(버전) 확인
프로젝트 구조
src/
├── __init__.py # 패키지 초기화
├── server.py # MCP 서버 메인 로직 (실행 파일)
├── zabbix_api.py # Zabbix API 연결 및 호출 관리
├── tools.py # MCP 도구 정의 및 핸들러
└── config.py # 설정 및 환경 변수 관리
pyproject.toml # 프로젝트 설정 및 의존성
README.md # 프로젝트 문서
설치 및 설정
1. 의존성 설치
프로젝트를 클론한 후 의존성을 설치하세요:
# uv가 설치되어 있지 않다면 먼저 설치
pip install uv
# 의존성 설치 및 가상환경 생성
uv sync
필요한 의존성:
2. MCP 클라이언트 등록 (공통 가이드)
아래 JSON 예시는 다양한 MCP 클라이언트에서 공통으로 사용하는 형식입니다. 실제 설정 파일 위치와 키 이름은 클라이언트마다 다를 수 있으니, 사용 중인 MCP 클라이언트 문서를 참고해 동일한 구조로 등록하세요.
API 토큰 사용 (권장):
{
"mcpServers": {
"zabbix": {
"command": "python",
"args": ["src/server.py"],
"cwd": "/path/to/your/zabbix-mcp-server",
"env": {
"ZABBIX_URL": "https://your-zabbix-server.com/api_jsonrpc.php",
"ZABBIX_API_TOKEN": "your_api_token_here"
},
"disabled": false,
"autoApprove": ["list_problems", "list_triggers"]
}
}
}
사용자명/비밀번호 사용:
{
"mcpServers": {
"zabbix": {
"command": "python",
"args": ["src/server.py"],
"cwd": "/path/to/your/zabbix-mcp-server",
"env": {
"ZABBIX_URL": "https://your-zabbix-server.com/api_jsonrpc.php",
"ZABBIX_USER": "your_username",
"ZABBIX_PASSWORD": "your_password"
},
"disabled": false,
"autoApprove": ["list_problems", "list_triggers"]
}
}
}
참고: 일부 클라이언트는 설정 파일이 JSON이 아닌 다른 포맷이거나, mcpServers 대신 별도의 섹션명을 사용할 수 있습니다. 이 경우에도 위 필드(command, args, cwd, env)를 동일하게 매핑해 등록하면 됩니다.
uvx를 사용한 등록 (패키지 배포 후)
{
"mcpServers": {
"zabbix": {
"command": "uvx",
"args": ["mcp-zabbix-server"],
"env": {
"ZABBIX_URL": "https://your-zabbix-server.com/api_jsonrpc.php",
"ZABBIX_API_TOKEN": "your_api_token_here"
},
"disabled": false,
"autoApprove": ["list_problems", "list_triggers"]
}
}
}
3. 서버 테스트 (선택 사항)
로컬에서 직접 실행하여 테스트할 수 있습니다:
# 1. 의존성 설치 (필수)
uv sync
# 2. 환경 변수 설정
export ZABBIX_URL="https://your-zabbix-server.com/api_jsonrpc.php"
export ZABBIX_API_TOKEN="your_api_token_here"
# 3. src 디렉터리에서 실행 (중요!)
cd src
python server.py
# 또는 uv를 사용하여 실행
cd src
uv run python server.py
중요한 실행 방법:
주의 사항:
환경 변수 설정
MCP 설정의 env 섹션에서 다음 환경 변수를 설정해야 합니다:
필수 환경 변수
인증 방법 (둘 중 하나 선택)
방법 1: API 토큰 (권장)
방법 2: 사용자명/비밀번호
선택 환경 변수
ZABBIX_VERIFY_SSL: Zabbix API 인증서 검증 여부 (true/false, 기본값 true). 자체 서명 인증서일 경우 false로 설정.
ZABBIX_TIMEOUT: Zabbix API 요청 타임아웃(초). 기본값 30.
사용법
문제 목록 조회
# 최근 60분 이내 발생한 문제 조회 (기본값)
list_problems()
# 최근 30분 이내 발생한 문제 조회
list_problems(recent=30)
# 최대 50개의 문제만 조회
list_problems(limit=50)
트리거 목록 조회
# 모든 활성 트리거 조회
list_triggers()
# High 이상 심각도의 트리거만 조회
list_triggers(min_severity=4)
# 최대 20개의 트리거만 조회
list_triggers(limit=20)
헬스 체크
# Zabbix API 버전 확인 (연결/인증/SSL 문제 진단에 유용)
zabbix_health()
API 응답 형식
Problems 응답
{
"problems": [
{
"eventid": "12345",
"clock": 1703123456,
"timestamp": "2023-12-21T10:30:56",
"name": "High CPU usage on server01",
"severity": 4,
"severity_name": "High",
"hosts": ["server01.example.com"],
"acknowledged": false
}
],
"total_count": 1,
"query_params": {
"recent_minutes": 60,
"limit": 100
},
"message": "최근 60분 이내 발생한 문제 1개를 조회했습니다."
}
Triggers 응답
{
"triggers": [
{
"triggerid": "67890",
"description": "CPU usage > 90%",
"priority": 4,
"priority_name": "High",
"hosts": ["server01.example.com"],
"lastchange": 1703123456,
"lastchange_timestamp": "2023-12-21T10:30:56",
"value": 1
}
],
"total_count": 1,
"query_params": {
"min_severity": 0,
"limit": 100
},
"message": "심각도 0 이상의 활성 트리거 1개를 조회했습니다."
}
심각도 레벨
0: Not classified
1: Information
2: Warning
3: Average
4: High
5: Disaster
문제 해결
의존성 오류
# ModuleNotFoundError가 발생하는 경우
uv sync # 의존성 재설치
# uv가 없는 경우 pip 사용
pip install mcp[cli] requests
Import 오류 (No such file or directory)
# 상대 import 오류가 발생하는 경우
cd src # src 디렉터리로 이동
python server.py # 해당 디렉터리에서 실행
# 또는 PYTHONPATH 설정
export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"
python src/server.py
환경 변수 오류
인증 오류
연결 오류
Zabbix 서버가 실행 중인지 확인하세요
네트워크 연결을 확인하세요
방화벽 설정을 확인하세요
권한 오류
MCP 서버 연결 확인
사용 중인 MCP 클라이언트의 서버/도구 패널 또는 로그 뷰어에서 상태를 확인하세요:
MCP 클라이언트의 서버 목록에서 "zabbix" 확인
연결 실패 시 클라이언트 로그/콘솔 출력 확인
환경 변수와 실행 경로(cwd)가 올바른지 재점검