Zabbix AI CLI — Servidor MCP de Zabbix y CLI para agentes de IA

zabbix-ai-cli es un servidor MCP de Zabbix y un cliente de línea de comandos en un único binario Go. Proporciona a Claude Code, Claude Desktop, Codex, Cursor y cualquier otro cliente del Model Context Protocol un acceso orientado a tareas a Zabbix — qué está roto ahora mismo, por qué un host está en silencio, por qué nunca llegó una alerta — con salida acotada, un contrato JSON estable y sin cambios en Zabbix sin la aprobación de una persona.

Está pensado para quienes reciben los avisos: equipos de SRE y DevOps que ejecutan Zabbix y quieren que un agente triaje un incidente sin entregarle toda la API.

Requiere Zabbix 6.4 o superior. La autenticación con token Bearer llegó en 6.4 y es el único esquema implementado; las versiones anteriores esperan el token en el cuerpo de la solicitud.

Nunca contacta con un modelo de lenguaje. La IA decide, este programa ejecuta, Zabbix monitoriza.

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

Por qué no otro envoltorio de la API de Zabbix

Envolver host.get, problem.get y history.get entrega al agente los bordes afilados de la API junto con su poder. En un servidor Zabbix 7.4 actual:

• problem.get no tiene selectHosts, por lo que una lista de problemas llega sin hosts.

• history.get por defecto usa la tabla numérica sin signo y devuelve nada para un elemento flotante — silenciosamente, sin error.

• item.lastvalue e item.lastclock todavía existen y han devuelto un "0" constante durante varias versiones principales.

• host.available se eliminó en 5.4; la disponibilidad vive en la interfaz.

• event.acknowledge toma una máscara de bits cuya propia documentación se contradice.

• searchWildcardsEnabled: true desactiva la coincidencia implícita de subcadenas, convirtiendo un fragmento de nombre en una coincidencia exacta que silenciosamente no encuentra nada.

Cada uno de esos produce una respuesta segura pero incorrecta en lugar de un error. Esta herramienta los absorbe detrás de comandos que describen la tarea en lugar del endpoint.

Related MCP server: Zabbix MCP Server

Qué hace

Seguridad

Las operaciones de lectura se ejecutan de inmediato. Nada más lo hace.

No hay ningún parámetro MCP que aplique un cambio, y añadir uno no ayudaría: una confirmación que un agente puede enviar es una confirmación que una inyección de prompt puede enviar. La aprobación vive en un terminal, fuera del contexto del modelo.

$ 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

Antes de que un plan se ejecute, sus parámetros se vuelven a calcular el hash, se comprueba su fecha límite y se releen sus precondiciones desde Zabbix. Una ventana que ha sido reemplazada desde que se hizo el plan se rechaza, no se elimina. Cada cambio aplicado se añade a un registro de auditoría.

Esto importa más de lo que importaría un rechazo. Cuando la herramienta que esto reemplaza bloqueaba una escritura, el trabajo se hacía de todos modos con un token copiado de un contenedor — perdiendo el rastro de auditoría sin prevenir nada. Un camino permitido que se registra supera a un rechazo que se evita.

Instalar

Los archivos precompilados y la imagen ghcr.io se publican con cada versión etiquetada. Hasta que llegue la primera etiqueta, compila desde el código fuente con cualquiera de los dos métodos siguientes.

Para un binario nativo del host, usa Go 1.25 o superior:

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

Los objetivos de Make están orientados a contenedores y no requieren Go en el host:

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

Configurar

zabbix-ai-cli login --profile prod

Pide la URL y el token de API, verifica el token contra el servidor y lo almacena. El token nunca se acepta como bandera, porque los valores de las banderas son visibles en el historial del shell y en la lista de procesos; en su lugar, canalízalo:

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

Las escrituras están desactivadas hasta que a un perfil se le conceda el alcance para ellas:

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

Consulta docs/authentication.md para el orden de resolución y los casos sin interfaz gráfica y en contenedor.

Añadir el servidor MCP de Zabbix a tu cliente de IA

El cliente MCP nunca ve el token de Zabbix. Se resuelve dentro del proceso del servidor a partir del perfil que configuraste, por lo que la credencial nunca entra en el contexto de un modelo ni en el archivo de configuración de un cliente.

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 y otros clientes MCP

Cualquier cliente que hable stdio acepta los mismos dos campos — comando zabbix-ai-cli, argumentos ["mcp", "--profile", "prod"]. Para un cliente que prefiera HTTP en su lugar:

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

Rechaza una dirección enrutable a menos que pases --allow-remote junto con un token Bearer, porque un endpoint MCP sin autenticación es una ruta sin autenticación hacia Zabbix. Consulta 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

Herramientas MCP

Catorce herramientas, no doscientas. Una superficie de herramientas grande le cuesta contexto a un agente antes de que haya hecho nada, y la mayoría nunca se llama.

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

Las operaciones de escritura no reciben una herramienta cada una. zabbix_plan_create toma un enum operation generado a partir del mismo registro del que se construye el CLI, por lo que la superficie de herramientas no crece a medida que se añaden operaciones.

Contrato JSON

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

Los errores llevan un código estable, si vale la pena reintentar y qué hacer a continuación:

{
  "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 imprime cada operación, sus parámetros y su JSON Schema, para que un agente pueda aprender la herramienta programáticamente en lugar de adivinar banderas.

Detalles completos en docs/json-output.md.

Documentación

• Autenticación y perfiles

• Línea de comandos

• Servidor MCP

• Habilidades

• Salida JSON y códigos de salida

• Modelo de seguridad

• Arquitectura y decisiones de diseño

Preguntas frecuentes

¿Qué es un servidor MCP de Zabbix?

Un servidor MCP es un pequeño programa que expone un sistema a un cliente de IA a través del Model Context Protocol. Un servidor MCP de Zabbix permite que Claude, Codex, Cursor y clientes similares consulten Zabbix — problemas, hosts, elementos, eventos, mantenimiento — como herramientas, en lugar de que el modelo adivine llamadas curl contra la API JSON-RPC.

¿Puede un agente de IA cambiar mi Zabbix a través de esto?

No por sí solo. Las operaciones de lectura se ejecutan de inmediato. Cada escritura produce un plan y se detiene. Aplicar ese plan es un comando que una persona ejecuta en su propio terminal: zabbix-ai-cli approve <plan-id>. No hay ningún parámetro MCP que aplique nada, y una prueba falla la compilación si alguna vez se añade uno.

¿Envía mis datos de monitorización a un proveedor de IA?

No. Este programa nunca contacta con un modelo de lenguaje. Habla con Zabbix e imprime JSON. Lo que tu cliente MCP haga con esa salida es entre tú y tu cliente.

¿Qué versiones de Zabbix se soportan?

Zabbix 6.4 y superiores, porque la autenticación con token Bearer llegó en 6.4. Desarrollado y probado contra Zabbix 7.4.

¿Necesito tener Go instalado?

No. make build compila dentro de Docker y no necesita nada en el host excepto Docker mismo. go install está ahí para un binario nativo del host, y cada versión etiquetada publica archivos para Linux, macOS y Windows con sumas de verificación, junto con una imagen de contenedor en ghcr.io.

¿En qué se diferencia esto de un servidor MCP que envuelve la API de Zabbix?

Un envoltorio delgado entrega al agente los bordes afilados de la API: problem.get sin hosts, history.get devolviendo silenciosamente nada para elementos flotantes, lastvalue congelado en "0". Esos producen respuestas seguras pero incorrectas en lugar de errores. Esta herramienta responde preguntas — "qué está roto", "por qué no llegó esta alerta" — y absorbe las trampas detrás de ellas. También incluye catorce herramientas en lugar de doscientas, porque una superficie de herramientas grande gasta el contexto de un agente antes de que haga cualquier trabajo.

¿Puedo seguir llamando a la API cruda de Zabbix?

Sí, a través de api call, bajo las mismas reglas de aprobación. Los métodos que entregan credenciales o ejecutan código se rechazan directamente — incluido el camino largo, como crear un script y hacer que una acción lo ejecute.

¿Funciona sin un cliente de IA en absoluto?

Sí. Es un CLI normal con tablas legibles para humanos, salida JSON y códigos de salida documentados, por lo que es igualmente utilizable desde un shell o un trabajo de CI.

Compatibilidad

Zabbix 6.4 y superiores. La autenticación con token Bearer llegó en 6.4 y es el único esquema implementado. El comportamiento dependiente de la versión se verifica explícitamente, por lo que una incompatibilidad se informa en lugar de devolver un resultado vacío.

Desarrollado y probado contra Zabbix 7.4.

Licencia

Apache-2.0. Consulta LICENSE.

Zabbix es una marca comercial de Zabbix LLC. Este proyecto es un proyecto de código abierto independiente y no está afiliado ni respaldado por Zabbix LLC.