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

필요한 의존성:

mcp[cli]>=1.13.1: MCP 서버 프레임워크
requests>=2.31.0: HTTP 요청 라이브러리

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

중요한 실행 방법:

반드시 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.

사용법

문제 목록 조회

# 최근 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

환경 변수 오류

MCP 설정의 env 섹션에 필수 환경 변수가 모두 설정되었는지 확인하세요
ZABBIX_URL이 올바른 JSON-RPC API 엔드포인트인지 확인하세요 (보통 /api_jsonrpc.php로 끝남)

인증 오류

API 토큰이 유효한지 확인하세요
사용자명/비밀번호가 정확한지 확인하세요
Zabbix 서버 URL이 올바른지 확인하세요

연결 오류

Zabbix 서버가 실행 중인지 확인하세요
네트워크 연결을 확인하세요
방화벽 설정을 확인하세요

권한 오류

사용자가 문제와 트리거를 조회할 권한이 있는지 확인하세요
API 토큰에 적절한 권한이 부여되었는지 확인하세요

MCP 서버 연결 확인

사용 중인 MCP 클라이언트의 서버/도구 패널 또는 로그 뷰어에서 상태를 확인하세요:

MCP 클라이언트의 서버 목록에서 "zabbix" 확인
연결 실패 시 클라이언트 로그/콘솔 출력 확인
환경 변수와 실행 경로(cwd)가 올바른지 재점검