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 클라이언트의 서버/도구 패널 또는 로그 뷰어에서 상태를 확인하세요:

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