README.md•7.97 kB
# 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. 의존성 설치
프로젝트를 클론한 후 의존성을 설치하세요:
```bash
# uv가 설치되어 있지 않다면 먼저 설치
pip install uv
# 의존성 설치 및 가상환경 생성
uv sync
```
**필요한 의존성:**
- `mcp[cli]>=1.13.1`: MCP 서버 프레임워크
- `requests>=2.31.0`: HTTP 요청 라이브러리
### 2. MCP 클라이언트 등록 (공통 가이드)
아래 JSON 예시는 다양한 MCP 클라이언트에서 공통으로 사용하는 형식입니다. 실제 설정 파일 위치와 키 이름은 클라이언트마다 다를 수 있으니, 사용 중인 MCP 클라이언트 문서를 참고해 동일한 구조로 등록하세요.
**API 토큰 사용 (권장):**
```json
{
"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"]
}
}
}
```
**사용자명/비밀번호 사용:**
```json
{
"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를 사용한 등록 (패키지 배포 후)
```json
{
"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. 서버 테스트 (선택 사항)
로컬에서 직접 실행하여 테스트할 수 있습니다:
```bash
# 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
```
**중요한 실행 방법:**
- 반드시 `src` 디렉터리 내에서 실행해야 합니다
- 프로젝트 루트에서 `python src/server.py`로 실행하면 import 오류가 발생할 수 있습니다
**주의 사항:**
- MCP 서버는 STDIO 기반으로 동작하므로 직접 실행 시 입출력이 제한됩니다
- 실제 테스트는 사용 중인 MCP 클라이언트를 통해 진행하는 것을 권장합니다
## 환경 변수 설정
MCP 설정의 `env` 섹션에서 다음 환경 변수를 설정해야 합니다:
### 필수 환경 변수
- `ZABBIX_URL`: Zabbix 서버의 JSON-RPC API URL
### 인증 방법 (둘 중 하나 선택)
**방법 1: API 토큰 (권장)**
- `ZABBIX_API_TOKEN`: Zabbix API 토큰
**방법 2: 사용자명/비밀번호**
- `ZABBIX_USER`: Zabbix 사용자명
- `ZABBIX_PASSWORD`: Zabbix 비밀번호
### 선택 환경 변수
- `ZABBIX_VERIFY_SSL`: Zabbix API 인증서 검증 여부 (`true`/`false`, 기본값 `true`). 자체 서명 인증서일 경우 `false`로 설정.
- `ZABBIX_TIMEOUT`: Zabbix API 요청 타임아웃(초). 기본값 `30`.
## 사용법
### 문제 목록 조회
```python
# 최근 60분 이내 발생한 문제 조회 (기본값)
list_problems()
# 최근 30분 이내 발생한 문제 조회
list_problems(recent=30)
# 최대 50개의 문제만 조회
list_problems(limit=50)
```
### 트리거 목록 조회
```python
# 모든 활성 트리거 조회
list_triggers()
# High 이상 심각도의 트리거만 조회
list_triggers(min_severity=4)
# 최대 20개의 트리거만 조회
list_triggers(limit=20)
```
### 헬스 체크
```python
# Zabbix API 버전 확인 (연결/인증/SSL 문제 진단에 유용)
zabbix_health()
```
## API 응답 형식
### Problems 응답
```json
{
"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 응답
```json
{
"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
## 문제 해결
### 의존성 오류
```bash
# ModuleNotFoundError가 발생하는 경우
uv sync # 의존성 재설치
# uv가 없는 경우 pip 사용
pip install mcp[cli] requests
```
### Import 오류 (No such file or directory)
```bash
# 상대 import 오류가 발생하는 경우
cd src # src 디렉터리로 이동
python server.py # 해당 디렉터리에서 실행
# 또는 PYTHONPATH 설정
export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"
python src/server.py
```
### 환경 변수 오류
- MCP 설정의 `env` 섹션에 필수 환경 변수가 모두 설정되었는지 확인하세요
- `ZABBIX_URL`이 올바른 JSON-RPC API 엔드포인트인지 확인하세요 (보통 `/api_jsonrpc.php`로 끝남)
### 인증 오류
- API 토큰이 유효한지 확인하세요
- 사용자명/비밀번호가 정확한지 확인하세요
- Zabbix 서버 URL이 올바른지 확인하세요
### 연결 오류
- Zabbix 서버가 실행 중인지 확인하세요
- 네트워크 연결을 확인하세요
- 방화벽 설정을 확인하세요
### 권한 오류
- 사용자가 문제와 트리거를 조회할 권한이 있는지 확인하세요
- API 토큰에 적절한 권한이 부여되었는지 확인하세요
### MCP 서버 연결 확인
사용 중인 MCP 클라이언트의 서버/도구 패널 또는 로그 뷰어에서 상태를 확인하세요:
1. MCP 클라이언트의 서버 목록에서 "zabbix" 확인
2. 연결 실패 시 클라이언트 로그/콘솔 출력 확인
3. 환경 변수와 실행 경로(`cwd`)가 올바른지 재점검