개요: 이것은 무엇인가? · 기능
설치: 빠른 시작 · 설치 · 업그레이드 · 최초 관리자 접근
구성: 참고 자료 · OAuth 2.1 · 공개 URL · TLS / HTTPS · 토큰 예산
사용: 클라이언트 마법사 · AI 클라이언트 · 프롬프트 · 도구 · 매개변수 · PDF 보고서
운영: 설치 프로그램 CLI · 업데이트 알림 · 호환성 · 개발 · 관련 프로젝트 · 라이선스
MCP(Model Context Protocol)는 AI 비서(ChatGPT, Claude, VS Code Copilot, JetBrains AI, Codex 등)가 외부 도구를 사용할 수 있게 하는 개방형 표준입니다. 이 서버는 전체 Zabbix API를 MCP 도구로 노출하여, 모든 호환 가능한 AI 비서가 호스트 조회, 문제 확인, 템플릿 관리, 이벤트 승인 및 기타 모든 Zabbix 작업을 수행할 수 있도록 합니다.
이 서버는 독립형 HTTP 서비스로 실행됩니다. AI 클라이언트는 네트워크를 통해 여기에 연결합니다.
완벽한 API 커버리지 - 모든 58개 Zabbix API 그룹(223개 도구): 호스트, 문제, 트리거, 템플릿, 사용자, 대시보드 등
확장 도구(14) -
사전 상관관계 보기: host_status_get, hostgroup_overview_get, infrastructure_summary_get, item_history_summary_get, problem_active_get (3~5개의 원시 API 호출을 하나의 왕복으로 통합). 또한 graph_render(PNG 내보내기), anomaly_detect(z-score 분석), capacity_forecast(선형 회귀), item_threshold_search(lastvalue 임계값으로 항목 필터링), report_generate(PDF 보고서), action_prepare/action_confirm(2단계 쓰기 승인), health_check(서버 진단) 및 zabbix_raw_api_call
(언래핑된 메서드에 대한 관리자 비상구(admin escape hatch)). 관리자 웹 포털 (Admin web portal) - 토큰, 사용자, 서버, 템플릿, 설정 및 감사 로그를 관리하는 포트 9090의 전체 웹 UI; 다크/라이트 모드; 클릭만으로 가능한 **클라이언트 MCP 마법사 (Client MCP Wizard) (베타)**가 14개 AI 클라이언트(Claude, Codex, Cursor, Cline, VS Code, JetBrains, Goose, Open WebUI, 5ire, Gemini CLI, n8n 등)를 위한 복사-붙여넣기 준비가 된 설정 스니펫을 생성합니다. 다중 토큰 인증 (Multi-token authentication) - 범위(scope), IP 제한, 서버 바인딩, 만료일이 있는 이름 지정 토큰; 관리자 포털, CLI (generate-token), 또는 config.toml을 통해 관리됩니다. 다중 서버 지원 (Multi-server support) - 별도의 토큰으로 여러 Zabbix 인스턴스(운영 환경, 스테이징 등)에 연결합니다. HTTP + SSE 전송 (HTTP + SSE transports) - 스트리밍 가능한 HTTP(권장) 및 세션 관리가 부족한 n8n과 같은 클라이언트를 위한 SSE를 지원합니다. 도구 필터링 (Tool filtering) - 카테고리(monitoring, alerts, users, extensions 등) 또는 개별 API 접두사로 노출되는 도구를 제한하여 도구 카탈로그 크기를 줄이고 LLM 컨텍스트 한계 내에 머무르게 합니다(아래 토큰 예산 참조). 간결한 출력 모드 (Compact output mode) - 기본적으로 메서드가 핵심 필드만 반환하도록 하여 응답 토큰 사용량을 줄입니다. LLM은 전체 세부 정보를 위해 extend를 요청할 수 있습니다. LLM 친화적 정규화 (LLM-friendly normalizations) - 심볼릭 열거형 이름, 자동 채우기 기본값, 전처리 정리, 타임스탬프 변환을 제공합니다. 단일 설정 파일 (Single config file) - 여러 환경 변수 대신 하나의 TOML 파일을 사용합니다. 읽기 전용 모드 (Read-only mode) - 실수로 인한 변경을 방지하기 위해 서버별 및 토큰별 쓰기 보호 기능을 제공합니다. 속도 제한 (Rate limiting) - Zabbix가 과부하되는 것을 막기 위해 클라이언트당 호출 예산(기본 300/분)을 설정합니다. 자동 재연결 (Auto-reconnect) - 세션 만료 시 투명하게 재인증합니다. 운영 환경 준비 완료 (Production-ready) - systemd 서비스, logrotate, Docker 지원, 보안 강화 기능을 제공합니다. 일반 폴백 (Generic fallback) - 명시적으로 정의되지 않은 모든 API 메서드에 대한 zabbix_raw_api_call 도구를 제공합니다. git clone https://github.com/initMAX/zabbix-mcp-server.git cd zabbix-mcp-server sudo ./deploy/install.sh ... 완료되었습니다. 서버는 http://127.0.0.1:8080/mcp에서 실행됩니다. 상세 가이드: INSTALL.md를 참조하십시오.
온프레미스(systemd) 및 Docker 배포 모두에 대한 단계별 설치 지침을 포함하며, 제거 방법, 보안 체크리스트, TLS 설정도 다룹니다.
- Python 3.10 이상이 설치된 Linux 서버
- Zabbix 서버에 대한 네트워크 접근 권한
- API 토큰(사용자 설정 > API 토큰)을 가진 Zabbix
API 토큰(User settings > API tokens). Zabbix 5.0 및 5.2 버전에는 API 토큰이 없으므로, 해당 두 버전의 경우만 명시적인 레거시 비밀번호 로그인이 존재합니다. 먼저 '레거시 인증(Legacy auth)'을 확인하고 경고문을 읽어보십시오.
git clone https://github.com/initMAX/zabbix-mcp-server.git
cd zabbix-mcp-server
sudo ./deploy/install.sh
설치 스크립트는 다음 작업을 수행합니다:
- 전용 시스템 사용자
zabbix-mcp 생성 (로그인 셸 없음)
/opt/zabbix-mcp/venv에 Python 가상 환경 생성- 서버 및 모든 종속성 설치
- 예제 설정을
/etc/zabbix-mcp/config.toml로 복사
- 시스템d 서비스 유닛 (
zabbix-mcp-server) 설치
/var/log/zabbix-mcp/*.log에 대한 로그로테이트 설정 (일별, 30일 보존)- 파일 권한 확인 및 문제 해결 제안
개발자가 자신의 컴퓨터에서 서버를 로컬로 실행하는 경우, sudo가 필요 없는 대체 설치 프로그램이 제공됩니다.
:
./deploy/install-user.sh # 설치
./deploy/install-user.sh update # git pull + pip + 재시작
./deploy/install-user.sh uninstall
이는 Python 3.10 이상을 감지하고, 리포지토리 내부에 가상 환경(virtualenv)을 생성하며, config.example.toml을 config.toml로 복사합니다 (이때 log_file은 사용자 쓰기 가능한 경로로 재작성됨). 또한 백그라운드 서비스를 등록합니다:
macOS: ~/Library/LaunchAgents/com.initmax.zabbix-mcp-server.plist에 LaunchAgent로 실행 (KeepAlive를 통한 자동 재시작)
Linux: 로그아웃 후에도 서비스가 유지되도록 loginctl enable-linger를 사용하여 ~/.config/systemd/user/zabbix-mcp-server.service에 systemd --user 유닛 등록
이는 로컬 개발용으로 의도된 것입니다. 프로덕션 서버에는 위에 제시된 일반적인 sudo ./deploy/install.sh를 사용하십시오.
cd zabbix-mcp-server
sudo ./deploy/install.sh update
이것이 전체 절차이며, 이후 수동 단계는 없습니다. v1.15+부터 update
이 명령어는 Git 동기화(sync), 패키지 재설치(reinstall), systemd 리로드(reload), 유효성 검사(validation) 및 서비스 재시작(restart)을 한 번에 처리합니다.
업데이트가 수행하는 작업:
- 현재 브랜치에서 최신 코드를 가져오고 (fast-forward 방식; 히스토리가 갈라진 경우
fetch + reset --hard origin/<branch>로 대체), 업데이트된 스크립트로부터 다시 실행됩니다.
- Python 패키지를
/opt/zabbix-mcp/venv에 재설치합니다.
- systemd 유닛 및 logrotate 설정을 새로 고칩니다 (릴리스 간 변경된 경우).
- 파일 권한을 확인하고 소유권 문제가 있는 경우 수정할 것을 제안합니다.
- 작은 마이그레이션(레거시 토큰, 보고서 템플릿)을 실행하고
config.toml의 유효성을 검사합니다 — 설정이 유효하지 않으면 중단됩니다.
systemctl restart zabbix-mcp-server를 통해 서비스를 재시작하고 구성된 포트에 대한 HTTP 상태 확인(health check)을 수행합니다.
유지되는 항목 (절대 덮어쓰지 않음):
/etc/zabbix-mcp/config.toml — Zabbix URL, API 토큰, MCP 토큰, 스코프, TLS 설정 등.- 관리 포털 사용자 (
[admin.users.*] 안에 있는 config.toml).
- 감사 로그(Audit log), 보고서 템플릿 및 모든 사용자 지정 데이터.
업데이트 중에는 /etc/zabbix-mcp/config.toml에 '✓ Config preserved at /etc/zabbix-mcp/config.toml (not overwritten)' 메시지가 표시됩니다. 이후에는 config.example.toml을 확인하여 릴리스에서 추가된 새 옵션이 있는지 확인하세요.
업데이트 중 PDF 보고서:
기본적으로 update는 현재의 보고 상태를 유지합니다 — PDF 보고서가 설치되었다면 그대로 유지되고, 그렇지 않았다면 추가되지 않습니다. 이를 변경하려면 다음을 사용하십시오:
# 기존 설치에 PDF 보고서를 활성화하는 경우
sudo ./deploy/install.sh update --with-reporting
# PDF 보고서 종속성 없이 업데이트 (더 작은 설치)
...
--with-reporting 플래그는 weasyprint, jinja2, 그리고 시스템 라이브러리(cairo, pango, gdk-pixbuf)를 가져옵니다. PDF 보고서에 대한 내용은 해당 문서를 참조하십시오.
매우 오래된 버전(v1.15 이전)에서 업그레이드하는 경우? 만약 update가 실패하면, 먼저 일회성 수동 동기화를 수행하세요: git fetch origin && git reset --hard origin/main sudo ./deploy/install.sh update
문제 해결: 문제가 발생하면 다음을 확인하세요:
sudo ./deploy/install.sh test-config # validate config.toml sudo journalctl -u zabbix-mcp-server -n 50 --no-pager
Zabbix 서버 세부 정보로 설정 파일을 편집합니다:
sudo nano /etc/zabbix-mcp/config.toml
최소 구성: Zabbix URL과 API 토큰만 채우면 됩니다:
[server]
transport = "http"
host = "127.0.0.1"
...
사용 가능한 모든 옵션과 자세한 설명은 config.example.toml에 문서화되어 있습니다.
이 설정 파일에는 서로 다른 목적을 가진 두 가지 유형의 토큰이 포함되어 있습니다:
┌────────────┐ MCP 토큰 (Bearer) ┌──────────────────┐ api_token ┌───────────────┐
│ MCP 클라이언트 ├──────────────────────► MCP 서버 ├─────────────────► Zabbix 서버 │
│ (AI / IDE) │ (선택 사항) │ (zabbix-mcp) │ (필수) │ │
...
api_token ([zabbix.*] 내): MCP 서버를 사용자의 Zabbix 인스턴스에 인증합니다. 이는 Zabbix 프론트엔드에서 생성하는 Zabbix API 토큰입니다. 필수적이며, 유일한 예외는 Zabbix 5.0 및 5.2의 명시적인 레거시 비밀번호 로그인 방식이므로 '레거시 인증'을 참조하세요.
생성 방법:
- Zabbix 프론트엔드에서: 사용자 → API 토큰 → API 토큰 생성 - 토큰이 속할 사용자를 선택합니다.
- 선택적으로 만료 날짜를 설정합니다.
- 생성된 토큰을 복사합니다. 이 토큰은 한 번만 표시됩니다.
토큰은 자신이 속한 Zabbix 사용자의 권한을 상속받습니다:
| 사용 사례 | 권장 Zabbix 역할 | read_only 설정 |
|---|
| 읽기 전용 모니터링 (문제, 호스트, 대시보드) | 필요한 호스트 그룹에 대한 읽기 액세스 권한이 있는 사용자 역할 | true |
| 전체 관리 (호스트, 템플릿, 트리거 생성) | 대상 호스트 그룹에 대한 읽기-쓰기 액세스 권한이 있는 관리자 역할 | false |
| 완전한 API 액세스 (사용자, 설정, 전역 스크립트) | 최고 관리자(Super admin) 역할 | false |
최소 권한의 원칙을 사용하십시오. MCP 서버에 필요한 권한만 가진 전용 Zabbix 사용자를 생성하세요.
활성화하기 전에 이 내용을 읽어보세요. Zabbix 5.0과 5.2는 업스트림 지원이 종료되었으며 API 토큰은 5.4에서 도입되었습니다. 유일한 방법은 사용자 이름(username)과 비밀번호(password)를 사용하는 것이며, 이는 이 서버가 폐기 가능한 범위가 지정된 토큰 대신 사용자 비밀번호를 구성 파일에 보유한다는 것을 의미합니다. 이는 사용자가 감수하기로 선택하는 보안 위험이며, 본 프로젝트는 전체 경로를 최선 노력(best effort)으로 취급합니다: 테스트 매트릭스에 포함되어 있지 않으며 라이브 5.x 버전을 대상으로 검증할 수 없습니다. 올바른 해결책은 Zabbix 업그레이드입니다. 아직 할 수 없다면, 그동안 서비스가 중단되지 않도록 존재합니다.
명시적으로 스위치를 켜야 합니다. 플래그 없이 사용자 이름(username)/비밀번호(password) 쌍을 사용하는 것은 폴백(fallback)이 아니라 구성 오류입니다:
[zabbix.old-prod]
url = "https://zabbix5.example.com"
legacy_auth = true # Zabbix 5.0 / 5.2 전용 스위치
...
서버가 적용하는 규칙:
legacy_auth = true와 api_token이 동일한 항목에 있는 것은 거부됩니다. 서버당 하나의 자격 증명만 사용해야 하며, 추론되는 값은 없습니다. legacy_auth = true 없이 사용자 이름(username)/비밀번호(password)는 거부됩니다.버전 잠금: 연결 시 서버는 apiinfo.version을 읽고 5.4 이상의 모든 레거시 로그인을 거부합니다. 현재 Zabbix에서는 이 플래그가 토큰이 존재하는 곳에서 사용되는 것을 방지하는 것 외에는 아무것도 하지 않으므로, 이를 이용해 우회할 수 없습니다.- 시작할 때마다 각 레거시 항목에 대해 Zabbix 버전을 명시하며 WARNING을 기록하므로, 운영 로그에서 선택 사항이 계속 눈에 띄게 유지됩니다. - 관리자 포털은 서버 카드와 추가/편집 양식 모두에서 동일한 경고를 표시하며, 비밀번호는 브라우저로 다시 전송되지 않습니다.
user.login 세션은 만료되며, Zabbix가 응답하면 서버가 자동으로 재인증합니다. 도구가 필요한 권한만 가진 전용 Zabbix 사용자를 사용하고, 쓰기 작업이 실제로 필요하지 않다면 read_only = true를 사용하세요.
비밀번호를 구성 파일에서 유지하기: 사용자 이름(username)과 비밀번호(password)는 ${ENV_VAR} 확장을 지원합니다. Docker의 경우, 변수를 .env에 넣으세요 (compose 파일이 env_file을 통해 주입합니다):
.env
ZABBIX_OLD_PASSWORD=your-password-here
The zabbix-utils 라이브러리를 사용하는 이 서버는 기본적으로 Zabbix 6.0 미만을 거부합니다. 버전 확인은 legacy_auth로 표시된 항목에 대해서만 완화되며, 토큰 인증에는 절대 적용되지 않습니다.
MCP 서버를 무단 접근으로부터 보호합니다. 구성하면 MCP 클라이언트는 모든 요청에 베어러 토큰(bearer token)을 포함해야 합니다: Authorization: Bearer <token>.
권장: 다중 토큰 시스템 (v1.16+) — 설치 프로그램, 관리자 포털 또는 수동으로 토큰을 생성합니다:
# 설치 프로그램을 통해 토큰 생성
sudo ./deploy/install.sh generate-token claude
# 또는 수동으로 생성
...
그런 다음 config.toml에 추가합니다:
:
[tokens.claude]
name = "Claude Code"
token_hash = "sha256:<paste hash>"
...
각 토큰은 독립적인 스코프(scope), IP 제한, 서버 바인딩 및 만료일을 가질 수 있습니다. 모든 옵션은 config.example.toml을 참조하십시오.
레거시: 단일 auth_token — 여전히 하위 호환성을 위해 지원됩니다:
[server]
auth_token = "your-secret-token-here"
레거시 auth_token은 첫 v1.16 시작 시 자동으로 [tokens.legacy]로 마이그레이션됩니다.