mcp-kafka

mcp-kafka

Um servidor Model Context Protocol para Apache Kafka. Ele permite que um cliente compatível com MCP (Claude Desktop, Claude Code, etc.) monitore e gerencie clusters Kafka — tópicos, partições, configurações e grupos de consumidores (incluindo lag) — com o comportamento controlado inteiramente por flags.

Seguro por padrão: inicia somente leitura, pode ser limitado a uma lista de tópicos permitidos, protege tópicos internos/críticos de mutação e condiciona operações destrutivas a uma aceitação explícita.

Recursos

• Monitoramento — informações do cluster/brokers, metadados e offsets de tópicos, grupos de consumidores e lag de consumidor por partição + total.
• Gerenciamento — criar tópicos, adicionar partições, alterar configurações de tópicos, redefinir offsets de grupos; excluir tópicos/grupos (admin).
• Modos de acesso — read-only → read-write → admin, em camadas, de modo que um modo nunca exponha ferramentas acima do seu nível.
• Flags de segurança — lista de tópicos permitidos, tópicos protegidos/internos, controle de exclusão, simulação (dry-run) e registro de auditoria em JSON (veja abaixo).
• Autenticação — texto simples, TLS e SASL (PLAIN / SCRAM-SHA-256 / SCRAM-SHA-512).

Modelo de segurança

Preocupação	Flag	Padrão	Efeito
O que o servidor pode fazer?	KAFKA_MODE	read-only	read-only expõe apenas monitoramento; read-write adiciona gerenciamento; admin adiciona exclusões. Ferramentas acima do modo nunca são registradas.
Quais tópicos estão no escopo?	KAFKA_TOPIC_ALLOWLIST	(todos)	Quando definido, operações em outros tópicos são recusadas.
Proteger tópicos internos	KAFKA_PROTECT_INTERNAL_TOPICS	true	Tópicos que começam com _ podem ser lidos, mas nunca modificados.
Proteger tópicos específicos	KAFKA_PROTECTED_TOPICS	(nenhum)	Tópicos adicionais somente leitura para sempre.
Pode excluir?	KAFKA_ALLOW_DELETE	false	delete_topic / delete_consumer_group precisam disso e do modo admin.
Pré-visualizar sem tocar no cluster	KAFKA_DRY_RUN	false	Ferramentas de escrita/admin validam + registram a intenção e retornam.
Trilha de auditoria	KAFKA_AUDIT_LOG	true	Emite uma linha JSON para stderr por operação protegida.

Ferramentas

Leitura (read-only+): cluster_info, list_topics, describe_topic, topic_offsets, list_consumer_groups, describe_consumer_group (com lag)

Escrita (read-write+): create_topic, create_partitions, alter_topic_config, reset_consumer_group_offsets

Admin (admin): delete_topic, delete_consumer_group (ambos precisam de KAFKA_ALLOW_DELETE)

Início rápido — adicione ao seu agente

Publicado no npm como @dockndevai/mcp-kafka. Sem necessidade de clone ou build — seu cliente MCP o executa sob demanda com npx. Comece no modo read-only; veja .env.example para todas as variáveis e docs/CLIENTS.md para o guia completo por cliente.

Claude Code (CLI)

claude mcp add kafka -e KAFKA_BROKERS="localhost:9092" -e KAFKA_MODE="read-only" -- npx -y @dockndevai/mcp-kafka

Claude Desktop · Cursor · Windsurf — mesmo bloco em claude_desktop_config.json, .cursor/mcp.json ou ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "kafka": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-kafka"
      ],
      "env": {
        "KAFKA_BROKERS": "localhost:9092",
        "KAFKA_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — em ~/.codex/config.toml:

[mcp_servers.kafka]
command = "npx"
args = ["-y", "@dockndevai/mcp-kafka"]
env = { KAFKA_BROKERS = "localhost:9092", KAFKA_MODE = "read-only" }

VS Code (GitHub Copilot, modo Agente) — em .vscode/mcp.json:

{
  "servers": {
    "kafka": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-kafka"
      ],
      "env": {
        "KAFKA_BROKERS": "localhost:9092",
        "KAFKA_MODE": "read-only"
      }
    }
  }
}

Exemplos de prompts

• "Quais grupos de consumidores têm mais lag agora?"
• "Descreva o tópico orders e mostre seus offsets."
• "Crie um tópico events com 6 partições e retenção de 7 dias." (requer read-write)

Executar a partir do código-fonte (desenvolvimento)

Prefira o pacote publicado acima. Para executar a partir de um clone:

npm install
npm run build
node dist/index.js   # with the environment variables set

Desenvolvimento

npm run dev
npm test
npm run typecheck

Publicação

Este servidor inclui um server.json para o registro oficial de MCP e um mcpName para validação de propriedade no npm. Veja PUBLISHING.md para publicar no npm e listar no registro MCP, Smithery, Glama, Cursor e PulseMCP.

Licença

MIT