# 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`)가 올바른지 재점검