Zabbix 8 + MCP: converse com o seu Zabbix usando IA

Home Blog
No Comment

Zabbix 8 + MCP: converse com o seu Zabbix usando IA

Neste passo a passo você instala o MCP server do Zabbix no servidor e conecta o Claude CLI do seu notebook a ele. No fim, você pergunta em português, por exemplo “quais problemas estão abertos?”, e a IA consulta o Zabbix e responde.

O que é o MCP?

MCP (Model Context Protocol) é um padrão que permite a uma IA usar ferramentas externas. O MCP server do Zabbix é o “tradutor” entre a IA e a API do Zabbix: a IA pede, ele consulta o Zabbix e devolve a resposta.

 NOTEBOOK                    SERVIDOR (Ubuntu)
┌──────────────┐        ┌───────────────────────────────┐
│  Claude CLI  │ ─────► │  MCP server  ─────►  Zabbix   │
│  (a IA)      │ :8443  │  (tradutor)          (API)    │
└──────────────┘        └───────────────────────────────┘

A IA só enxerga o que o usuário dono do token enxerga. É por isso que, no passo 4, você cria um token.

O que você precisa

  • Um servidor Ubuntu com Zabbix 8.0 já instalado (server e frontend) e com o repositório do Zabbix configurado.
  • Um notebook na mesma rede, com o Claude CLI instalado.
  • Acesso root no servidor.

Nos comandos, troque IP-DO-SERVIDOR pelo IP real do seu servidor. Neste manual a rede é 192.168.1.0/24 (ou seja, 192.168.1.1 até 192.168.1.254). Se a sua rede for outra, troque no passo 2.

O pacote do MCP está na versão 8.0.0~rc1, ainda em desenvolvimento. É ótimo para estudar e testar, mas não use em produção.

Passo 1: instalar o pacote (no servidor)

apt install -y zabbix-mcp-server

Isso instala o programa e cria o arquivo de configuração /etc/zabbix/zabbix_mcp_server.conf.

Passo 2: editar o arquivo de configuração (no servidor)

Abra o arquivo no editor nano:

nano /etc/zabbix/zabbix_mcp_server.conf

Os três parâmetros para ajustar

Pesquise cada um com Ctrl + W. Se a linha tiver # na frente (comentário, que o programa ignora), apague o #. Se o parâmetro não existir, escreva a linha no final do arquivo.

1. FrontendURL: onde está a API do Zabbix

FrontendURL=http://127.0.0.1/zabbix/api_jsonrpc.php

É o endereço da API do Zabbix, sempre terminando em api_jsonrpc.php. Nos pacotes Ubuntu com Apache, o frontend fica em /zabbix/. Se o seu frontend estiver na raiz do site, tire o /zabbix da URL.

2. ListenIP: de onde o MCP aceita conexões

ListenIP=0.0.0.0

0.0.0.0 significa “aceitar conexões vindas da rede”. Sem isso, só o próprio servidor consegue conectar.

3. AllowedIP: quem tem permissão para conectar

AllowedIP=127.0.0.1,::1,192.168.1.0/24

Só os endereços dessa lista conseguem usar o MCP. O 127.0.0.1 e o ::1 são o próprio servidor, e o 192.168.1.0/24 libera toda a rede 192.168.1.x. O valor padrão do arquivo é 127.0.0.1,::1, que bloqueia o notebook, por isso essa linha precisa mudar.

Salve com Ctrl + O, Enter, e saia com Ctrl + X.

Para conferir tudo que está ativo no arquivo (sem comentários):

grep -vE '^\s*(#|$)' /etc/zabbix/zabbix_mcp_server.conf

Devem aparecer as suas três linhas e, mais abaixo, as linhas DenyTool=... (explicadas no passo 8).

Passo 3: iniciar o serviço (no servidor)

systemctl enable --now zabbix-mcp-server
systemctl status zabbix-mcp-server

O enable --now liga o serviço agora e também a cada boot. No status, procure active (running) em verde.

Veja o log para confirmar:

tail -n 20 /var/log/zabbix/zabbix_mcp_server.log

Procure uma linha como MCP endpoint available at http://0.0.0.0:8443/mcp, 17 tools exposed. Isso significa que o MCP está no ar, na porta 8443, com 17 ferramentas disponíveis.

Se o serviço não subir, o motivo está no log. Quase sempre é um erro de digitação em FrontendURL ou AllowedIP.

Passo 4: criar o token (no frontend do Zabbix)

O token é a “senha” que a IA usa para falar com o Zabbix.

  1. Abra o Zabbix no navegador e vá em Users → API tokens → Create API token.
  2. Escolha o usuário, dê um nome (por exemplo claude-mcp) e defina uma data de expiração.
  3. Clique em Add e copie o token. Ele só aparece uma vez.

Importante: a IA tem exatamente as permissões do usuário escolhido. Com o Admin, ela enxerga e altera tudo. O mais seguro é criar um usuário só para isso, com permissão Read apenas nos grupos de hosts que a IA precisa ver.

Passo 5: testar a conexão (no notebook)

Antes de usar a IA, confirme que o notebook alcança o MCP:

No Windows (PowerShell):

$headers = @{ Authorization = "Bearer COLE-O-TOKEN-AQUI"; Accept = "application/json, text/event-stream" }
$body = '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
(Invoke-RestMethod -Uri "http://IP-DO-SERVIDOR:8443/mcp" -Method Post -Headers $headers -ContentType "application/json" -Body $body).result.tools.name

Se funcionar, aparece uma lista com o nome das ferramentas (host_get, problem_get e outras). Se não aparecer nada, apague o .result.tools.name do fim do comando para ver a resposta completa.

No PowerShell o comando curl é um apelido de outro comando e não aceita os mesmos parâmetros do Linux, por isso usamos o Invoke-RestMethod.

No Linux ou macOS:

curl -sS http://IP-DO-SERVIDOR:8443/mcp \
  -H "Authorization: Bearer COLE-O-TOKEN-AQUI" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Se voltar um texto JSON com uma lista de ferramentas, está funcionando.

Passo 6: conectar o Claude CLI (no notebook)

claude mcp add --transport http zabbix http://IP-DO-SERVIDOR:8443/mcp --header "Authorization: Bearer COLE-O-TOKEN-AQUI"

O comando vai todo em uma linha, e funciona igual no PowerShell, no Linux e no macOS. Ele cadastra o MCP no Claude CLI com o nome zabbix. Agora abra o Claude:

claude

E digite /mcp. O servidor zabbix deve aparecer como connected.

Passo 7: usar

Faça perguntas em português:

  • “Quais problemas estão abertos agora e qual a severidade?”
  • “Liste os hosts do Zabbix e quais triggers estão em problema.”
  • “Quais templates estão vinculados ao host Zabbix server?”

Na primeira vez, o Claude CLI pede permissão para usar cada ferramenta do MCP. Aprove.

Para testar uma pergunta de memória ou CPU (por exemplo, “qual o uso de memória do host X?”), a IA vai dizer que não consegue. Isso é normal e é corrigido no passo 8.

Passo 8: liberar a leitura de métricas (opcional)

Por segurança, o MCP vem com cinco ferramentas bloqueadas. No arquivo de configuração elas aparecem assim:

DenyTool=item_get
DenyTool=lld_get
DenyTool=interface_get
DenyTool=macro_get
DenyTool=history_get

Para a IA responder sobre CPU, memória, disco e outras métricas, ela precisa de duas ferramentas:

  • item_get: lista os itens de um host (por exemplo, “Memory utilization”).
  • history_get: lê os valores que o Zabbix coletou.

Para liberar, abra o arquivo, pesquise DenyTool com Ctrl + W e coloque um # na frente de só essas duas linhas:

# DenyTool=item_get
DenyTool=lld_get
DenyTool=interface_get
DenyTool=macro_get
# DenyTool=history_get

Salve, saia e reinicie o serviço:

systemctl restart zabbix-mcp-server

No log (tail -n 20 /var/log/zabbix/zabbix_mcp_server.log), a contagem passa de 17 para 19 ferramentas. No notebook, feche e abra o claude de novo para ele recarregar a lista, e pergunte: “Qual o uso de memória do host NOME-DO-HOST?”.

Deixe macro_get bloqueada: macros costumam guardar senhas.

Problemas comuns

O que aparece O que significa e como resolver
curl com 403 O IP do notebook não está em AllowedIP. Corrija no arquivo e rode systemctl restart zabbix-mcp-server. Se usou 192.168.1.0/24 e continua dando 403, liste o IP do notebook direto (192.168.1.50, por exemplo)
curl com 401 Faltou o header Authorization ou o token está errado ou expirou
curl com 400 Faltou um dos dois valores no header Accept
curl sem resposta ou Connection refused O serviço não está rodando, o ListenIP não é 0.0.0.0 ou o firewall bloqueia a porta 8443
Claude CLI conecta, mas dá erro 404 ao consultar o Zabbix A FrontendURL está errada (falta o /zabbix/ ou ele está sobrando). Corrija no passo 2 e reinicie o serviço
A IA diz que o host ou o item não existe O usuário dono do token não tem permissão Read nesse host. Ajuste em Users → User groups
A IA não mostra métricas As ferramentas item_get e history_get ainda estão bloqueadas. Veja o passo 8
O serviço não sobe Veja o motivo em tail -n 30 /var/log/zabbix/zabbix_mcp_server.log