zammad-mcp

MCP server para acessar a API do Zammad https://chamados.pop-rr.rnp.br.

Tools expostas

Tool	Descrição
zammad_ticket_search	Busca chamados (sintaxe de busca do Zammad)
zammad_ticket_get	Detalhes de um chamado (com artigos/histórico)
zammad_ticket_create	Cria um novo chamado
zammad_ticket_update	Atualiza estado/prioridade/grupo/responsável
zammad_ticket_add_article	Adiciona nota interna ou resposta a um chamado
zammad_user_search	Busca usuários (agentes/clientes)
zammad_user_get	Detalhes de um usuário
zammad_organization_search	Busca organizações
zammad_group_list	Lista os grupos (filas) de chamados

zammad_ticket_create/zammad_ticket_update aceitam tanto o nome (group, state, priority) quanto o id (group_id, state_id, priority_id) — o Zammad resolve nomes nesses campos automaticamente. Em article.internal/internal (add_article e create), o default é true (nota interna, não visível ao cliente) independente de type — para enviar um e-mail ao cliente, informe internal: false explicitamente.

Configuração

Variável	Descrição	Default
ZAMMAD_URL	Base URL da instância Zammad (sem /api/v1)	— (obrigatório)
ZAMMAD_TOKEN_FILE	Caminho do arquivo do token	/run/zammad/token
ZAMMAD_TOKEN	Token da API direto por env (a imagem grava no ZAMMAD_TOKEN_FILE)	—
MCP_PORT	Porta do endpoint HTTP (só na imagem Docker)	8000
MCP_PATH	Caminho do endpoint streamable-HTTP (só na imagem)	/mcp
NODE_TLS_REJECT_UNAUTHORIZED	Setar 0 se a instância usar certificado autoassinado (ex.: mkcert)	—

Forneça o token por ZAMMAD_TOKEN_FILE (arquivo/secret montado) ou por ZAMMAD_TOKEN (env) — a imagem materializa o env num arquivo no start. unset ZAMMAD_TOKEN no entrypoint tira o valor do ambiente do processo, mas não o esconde de docker inspect/Portainer quando fornecido como env var na stack (é metadado do container, não do processo) — se isso for uma preocupação, use secret de swarm (ZAMMAD_TOKEN_FILE apontando para um arquivo montado) em vez de env var.

Build & Run (local, stdio)

npm install
npm run build
npm test
ZAMMAD_URL=https://sua-instancia.example.com ZAMMAD_TOKEN_FILE=$(pwd)/.token node dist/index.js

Docker (streamable-HTTP via supergateway)

A imagem embute o servidor + supergateway, expondo o MCP em :8000/mcp.

docker build -t ghcr.io/marcelofmatos/zammad-mcp:local .
docker run --rm -p 8000:8000 \
  -e ZAMMAD_URL=https://sua-instancia.example.com \
  -e ZAMMAD_TOKEN=xxxxxxxx \
  ghcr.io/marcelofmatos/zammad-mcp:local
# health: curl localhost:8000/health   |   MCP: http://localhost:8000/mcp

Imagens publicadas no GHCR pelo workflow Release and build (dispatch manual; versiona SemVer via tags e dá push em ghcr.io/marcelofmatos/zammad-mcp).

Deploy no bot Apolo (PoP-RR)

Roda como serviço zammad-poprr na stack mcp-servers-anton (rede anton-mcp), registrado no mcp.json do bot como:

"zammad-poprr": { "type": "http", "url": "http://zammad-poprr:8080/mcp" }

Detalhes completos (compose do serviço, envs da stack, passos de deploy) na spec local em docs/superpowers/specs/2026-07-26-zammad-mcp-design.md (não versionada neste repositório).