Zabbix AI CLI — AI 에이전트용 Zabbix MCP 서버 및 CLI

zabbix-ai-cli는 하나의 Go 바이너리로 제공되는 Zabbix MCP 서버이자 명령줄 클라이언트입니다. Claude Code, Claude Desktop, Codex, Cursor 및 기타 모든 Model Context Protocol 클라이언트에 Zabbix에 대한 작업 지향적 접근을 제공합니다 — 지금 무엇이 고장났는지, 호스트가 왜 조용한지, 알림이 왜 도착하지 않았는지 — 출력을 제한하고, 안정적인 JSON 계약을 유지하며, 사람의 승인 없이는 Zabbix를 변경하지 않습니다.

페이지를 받는 사람들을 위한 것입니다: Zabbix를 운영하는 SRE 및 DevOps 팀이 전체 API를 넘겨주지 않고 에이전트가 인시던트를 분류하도록 하려는 경우입니다.

Zabbix 6.4 이상이 필요합니다. Bearer 토큰 인증은 6.4에서 도입되었으며 구현된 유일한 방식입니다. 이전 버전은 요청 본문에 토큰을 넣을 것으로 예상합니다.

이 프로그램은 언어 모델에 절대 접촉하지 않습니다. AI가 결정하고, 이 프로그램이 실행하며, Zabbix가 모니터링합니다.

zabbix-ai-cli login
zabbix-ai-cli problems list
zabbix-ai-cli host investigate server01
zabbix-ai-cli alert why 757474
zabbix-ai-cli mcp

왜 또 다른 Zabbix API 래퍼가 아닌가

host.get, problem.get, history.get를 래핑하면 에이전트에게 API의 강력함과 함께 날카로운 모서리를 넘겨줍니다. 현재 Zabbix 7.4 서버에서:

• problem.get에는 selectHosts가 없어서 문제 목록에 호스트가 포함되지 않습니다.

• history.get는 기본적으로 numeric-unsigned 테이블을 사용하며 float 항목에 대해 아무것도 반환하지 않습니다 — 오류 없이 조용히.

• item.lastvalue와 item.lastclock은 여전히 존재하며 여러 주요 릴리스 동안 상수 "0"을 반환해 왔습니다.

• host.available은 5.4에서 제거되었습니다. 가용성은 인터페이스에 있습니다.

• event.acknowledge는 문서 자체가 모순되는 비트마스크를 사용합니다.

• searchWildcardsEnabled: true는 암시적 부분 문자열 일치를 비활성화하여 이름 조각을 정확히 일치로 바꾸고 조용히 아무것도 찾지 못하게 합니다.

이 모든 것은 오류 대신 자신만만한 잘못된 답변을 생성합니다. 이 도구는 엔드포인트 대신 작업을 설명하는 명령 뒤에 이러한 함정을 흡수합니다.

Related MCP server: Zabbix MCP Server

기능

안전

읽기 작업은 즉시 실행됩니다. 다른 작업은 그렇지 않습니다.

변경을 적용하는 MCP 매개변수는 없으며, 추가해도 도움이 되지 않습니다: 에이전트가 보낼 수 있는 확인은 프롬프트 인젝션이 보낼 수 있는 확인입니다. 승인은 모델의 컨텍스트 밖, 터미널에 있습니다.

$ zabbix-ai-cli maintenance create "ms*" --for 2h

PLAN pl_cc89d2e87d15

Create maintenance "ms* (2h0m)" for 2h0m, 2026-08-21T05:39:00Z to 2026-08-21T07:39:00Z

Affects:
  host ms1.8qw.ru
  host ms10.8qw.ru
  ...

Risk: write
Expires: 2026-08-21T05:54:22Z

Nothing has changed yet.
To apply it: zabbix-ai-cli approve pl_cc89d2e87d15

계획이 실행되기 전에 매개변수가 다시 해시되고, 마감 시간이 확인되며, 사전 조건이 Zabbix에서 다시 읽힙니다. 계획이 만들어진 이후 교체된 창은 삭제되지 않고 거부됩니다. 적용된 모든 변경은 감사 로그에 추가됩니다.

이것은 거부보다 더 중요합니다. 이 도구가 대체한 도구가 쓰기를 차단했을 때, 작업은 컨테이너에서 복사된 토큰으로 어쨌든 수행되었습니다 — 감사 추적을 잃고 아무것도 방지하지 못했습니다. 기록된 허용 경로는 우회되는 거부보다 낫습니다.

설치

사전 빌드된 아카이브와 ghcr.io 이미지는 각 태그 릴리스와 함께 게시됩니다. 첫 번째 태그가 나올 때까지 아래 두 방법 중 하나로 소스에서 빌드하세요.

호스트 네이티브 바이너리의 경우 Go 1.25 이상을 사용하세요:

go install github.com/stufently/zabbix-ai-cli/cmd/zabbix-ai-cli@latest

# Or build the current checkout.
mkdir -p bin
go build -trimpath -o bin/zabbix-ai-cli ./cmd/zabbix-ai-cli

Make 타겟은 컨테이너 우선이며 호스트에 Go가 필요하지 않습니다:

make build      # Linux binary in ./bin, built inside Docker
make docker     # Linux container image for the MCP server

구성

zabbix-ai-cli login --profile prod

URL과 API 토큰을 묻고, 서버에 대해 토큰을 확인한 후 저장합니다. 토큰은 플래그로 절대 허용되지 않습니다. 플래그 값은 셸 기록과 프로세스 목록에 표시되기 때문입니다. 대신 파이프로 전달하세요:

printf %s "$TOKEN" | zabbix-ai-cli login --profile prod --url https://zabbix.example.com --token-stdin

프로필에 쓰기 범위가 부여될 때까지 쓰기는 꺼져 있습니다:

zabbix-ai-cli profile scopes prod --add maintenance

해석 순서와 헤드리스 및 컨테이너 사례는 docs/authentication.md를 참조하세요.

AI 클라이언트에 Zabbix MCP 서버 추가

MCP 클라이언트는 Zabbix 토큰을 절대 볼 수 없습니다. 구성한 프로필에서 서버 프로세스 내부에서 해석되므로 자격 증명이 모델의 컨텍스트나 클라이언트의 구성 파일에 들어가지 않습니다.

Claude Code

claude mcp add zabbix -- zabbix-ai-cli mcp --profile prod
zabbix-ai-cli skills install claude

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "zabbix": {
      "command": "zabbix-ai-cli",
      "args": ["mcp", "--profile", "prod"]
    }
  }
}

Codex

# ~/.codex/config.toml
[mcp_servers.zabbix]
command = "zabbix-ai-cli"
args = ["mcp", "--profile", "prod"]

zabbix-ai-cli skills install codex

Cursor, Windsurf, VS Code 및 기타 MCP 클라이언트

stdio를 사용하는 모든 클라이언트는 동일한 두 필드를 사용합니다 — 명령 zabbix-ai-cli, 인수 ["mcp", "--profile", "prod"]. HTTP를 원하는 클라이언트의 경우:

zabbix-ai-cli mcp --http 127.0.0.1:8000

--allow-remote와 함께 bearer 토큰을 전달하지 않으면 라우팅 가능한 주소를 거부합니다. 인증되지 않은 MCP 엔드포인트는 Zabbix로의 인증되지 않은 경로이기 때문입니다. docs/mcp.md를 참조하세요.

Docker

docker run --rm -i \
  -e ZABBIX_AI_CLI_URL=https://zabbix.example.com \
  -e ZABBIX_AI_CLI_TOKEN_FILE=/run/secrets/zabbix \
  -v /path/to/token:/run/secrets/zabbix:ro \
  ghcr.io/stufently/zabbix-ai-cli:latest mcp

MCP 도구

14개의 도구, 200개가 아닙니다. 큰 도구 표면은 에이전트가 아무것도 하기 전에 컨텍스트를 소비하며, 대부분은 호출되지 않습니다.

zabbix_problems           zabbix_metrics_latest      zabbix_unreachable
zabbix_problem            zabbix_metrics_history     zabbix_maintenance_list
zabbix_hosts              zabbix_alert_why           zabbix_api_call
zabbix_host_status        zabbix_resolve             zabbix_plan_create
zabbix_host_investigate                              zabbix_plan_status

쓰기 작업에는 각각 하나의 도구가 없습니다. zabbix_plan_create는 CLI가 구축된 동일한 레지스트리에서 생성된 operation 열거형을 사용하므로 작업이 추가되어도 도구 표면이 커지지 않습니다.

JSON 계약

{
  "ok": true,
  "data": {},
  "warnings": [],
  "meta": {
    "returned": 50,
    "total": 381,
    "truncated": true,
    "truncated_reason": "row_limit",
    "partial": false,
    "zabbix_version": "7.4.10"
  }
}

오류는 안정적인 코드, 재시도가 가치 있는지 여부, 다음에 무엇을 해야 하는지를 전달합니다:

{
  "ok": false,
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Zabbix rejected the configured API token",
    "retryable": false,
    "suggestion": "run 'zabbix-ai-cli login' to configure a new token"
  }
}

zabbix-ai-cli schema는 모든 작업, 매개변수 및 JSON Schema를 출력하므로 에이전트가 플래그를 추측하는 대신 프로그래밍 방식으로 도구를 배울 수 있습니다.

자세한 내용은 docs/json-output.md를 참조하세요.

문서

• 인증 및 프로필

• 명령줄

• MCP 서버

• 스킬

• JSON 출력 및 종료 코드

• 보안 모델

• 아키텍처 및 설계 결정

FAQ

Zabbix MCP 서버란 무엇인가요?

MCP 서버는 Model Context Protocol을 통해 AI 클라이언트에 시스템을 노출하는 작은 프로그램입니다. Zabbix MCP 서버는 Claude, Codex, Cursor 및 유사한 클라이언트가 JSON-RPC API에 대한 curl 호출을 추측하는 대신 문제, 호스트, 항목, 이벤트, 유지보수와 같은 Zabbix를 도구로 쿼리할 수 있게 합니다.

AI 에이전트가 이 도구를 통해 내 Zabbix를 변경할 수 있나요?

스스로는 불가능합니다. 읽기 작업은 즉시 실행됩니다. 모든 쓰기는 계획을 생성하고 중지합니다. 해당 계획을 적용하는 것은 사람이 자신의 터미널에서 실행하는 명령입니다: zabbix-ai-cli approve <plan-id>. 무엇이든 적용하는 MCP 매개변수는 없으며, 하나라도 추가되면 빌드가 실패하는 테스트가 있습니다.

모니터링 데이터를 AI 제공업체에 보내나요?

아니요. 이 프로그램은 언어 모델에 절대 접촉하지 않습니다. Zabbix와 통신하고 JSON을 출력합니다. MCP 클라이언트가 해당 출력으로 무엇을 하는지는 귀하와 클라이언트 간의 문제입니다.

어떤 Zabbix 버전을 지원하나요?

Zabbix 6.4 이상입니다. bearer 토큰 인증이 6.4에서 도입되었기 때문입니다. Zabbix 7.4에 대해 개발 및 테스트되었습니다.

Go를 설치해야 하나요?

아니요. make build는 Docker 내부에서 컴파일되며 호스트에는 Docker만 있으면 됩니다. go install은 호스트 네이티브 바이너리를 위한 것이며, 각 태그 릴리스는 체크섬과 함께 Linux, macOS, Windows용 아카이브와 ghcr.io의 컨테이너 이미지를 게시합니다.

Zabbix API를 래핑하는 MCP 서버와 어떻게 다른가요?

얇은 래퍼는 에이전트에게 API의 날카로운 모서리를 넘겨줍니다: 호스트 없는 problem.get, float 항목에 대해 조용히 아무것도 반환하지 않는 history.get, "0"에 고정된 lastvalue. 이러한 것들은 오류 대신 자신만만한 잘못된 답변을 생성합니다. 이 도구는 "무엇이 고장났는지", "이 알림이 왜 도착하지 않았는지"와 같은 질문에 답하고 그 뒤의 함정을 흡수합니다. 또한 200개가 아닌 14개의 도구를 제공합니다. 큰 도구 표면은 에이전트가 작업을 수행하기 전에 컨텍스트를 소비하기 때문입니다.

원시 Zabbix API를 여전히 호출할 수 있나요?

예, api call을 통해 동일한 승인 규칙 아래에서 가능합니다. 자격 증명을 제공하거나 코드를 실행하는 메서드는 완전히 거부됩니다 — 스크립트를 만들고 작업이 실행하도록 하는 것과 같은 우회 경로도 포함됩니다.

AI 클라이언트 없이도 작동하나요?

예. 사람이 읽을 수 있는 테이블, JSON 출력 및 문서화된 종료 코드를 가진 일반 CLI이므로 셸이나 CI 작업에서 동일하게 사용할 수 있습니다.

호환성

Zabbix 6.4 이상. Bearer 토큰 인증은 6.4에서 도입되었으며 구현된 유일한 방식입니다. 버전 종속 동작은 명시적으로 검증되므로 비호환성은 빈 결과를 반환하는 대신 보고됩니다.

Zabbix 7.4에 대해 개발 및 테스트되었습니다.

라이선스

Apache-2.0. LICENSE를 참조하세요.

Zabbix는 Zabbix LLC의 상표입니다. 이 프로젝트는 독립적인 오픈 소스 프로젝트이며 Zabbix LLC와 제휴하거나 보증하지 않습니다.