Kafka MCP Server

Um servidor MCP para Apache Kafka, permitindo que LLMs realizem operações Kafka como produzir e consumir mensagens.

GitHub
56
Experimente este MCPPatrocinado

Documentação

Kafka MCP Server

Um servidor Model Context Protocol (MCP) para Apache Kafka implementado em Go, utilizando franz-go e mcp-go.

Este servidor fornece uma implementação para interagir com Kafka através do protocolo MCP, permitindo que modelos de LLM executem operações comuns do Kafka por meio de uma interface padronizada.

Go Report Card GitHub Workflow Status Go Version Trivy Scan SLSA 3 Go Reference Docker Image GitHub Release License: MIT

Visão Geral

O Kafka MCP Server preenche a lacuna entre modelos de LLM e Apache Kafka, permitindo que eles:

  • Produzam e consumam mensagens de tópicos
  • Listem, descrevam e gerenciem tópicos
  • Monitorem e gerenciem grupos de consumidores
  • Avaliem a saúde e a configuração do cluster
  • Executem operações padrão do Kafka

Tudo através do protocolo padronizado Model Context Protocol (MCP).

Arquitetura

graph TB
    subgraph "MCP Client (AI Applications)"
        A[Claude Desktop]
        B[Cursor]
        C[Windsurf]
        D[ChatWise]
    end
    
    subgraph "Kafka MCP Server"
        E[MCP Protocol Handler]
        F[Tools Registry]
        G[Resources Registry]
        H[Prompts Registry]
        I[Kafka Client Wrapper]
    end
    
    subgraph "Apache Kafka Cluster"
        J[Broker 1]
        K[Broker 2]
        L[Broker 3]
        M[Topics & Partitions]
        N[Consumer Groups]
    end
    
    A --> E
    B --> E
    C --> E
    D --> E
    
    E --> F
    E --> G
    E --> H
    
    F --> I
    G --> I
    H --> I
    
    I --> J
    I --> K
    I --> L
    
    J --> M
    K --> M
    L --> M
    
    J --> N
    K --> N
    L --> N
    
    classDef client fill:#e1f5fe
    classDef mcp fill:#f3e5f5
    classDef kafka fill:#fff3e0
    
    class A,B,C,D client
    class E,F,G,H,I mcp
    class J,K,L,M,N kafka

Como funciona:

  1. Clientes MCP (aplicações de IA) conectam-se ao Kafka MCP Server via transporte stdio ou HTTP
  2. Servidor MCP expõe três tipos de capacidades:
    • Ferramentas - Operações diretas do Kafka (produzir/consumir mensagens, descrever tópicos, etc.)
    • Recursos - Relatórios de saúde do cluster e diagnósticos
    • Prompts - Fluxos de trabalho pré-configurados para operações comuns
  3. Wrapper do Cliente Kafka gerencia toda a comunicação com o Kafka usando a biblioteca franz-go
  4. Cluster Apache Kafka processa o streaming e o armazenamento real de mensagens

Modos de Transporte:

  • STDIO: Modo padrão, ideal para clientes MCP locais (Claude Desktop, Cursor, etc.)
  • HTTP: Permite acesso remoto com autenticação opcional OAuth 2.1

Tools

Prompts & Resources

Principais Recursos

  • Integração com Kafka: Implementação de operações comuns do Kafka via MCP
  • Segurança:
    • Suporte para autenticação SASL (PLAIN, SCRAM-SHA-256, SCRAM-SHA-512) e TLS
    • Autenticação OAuth 2.1 para transporte HTTP (modos Nativo e Proxy)
    • Suporte para provedores Okta, Google, Azure AD e HMAC
  • Transporte Flexível: STDIO para clientes locais, HTTP para acesso remoto
  • Tratamento de Erros: Tratamento de erros com feedback significativo
  • Opções de Configuração: Personalizável para diferentes ambientes
  • Prompts Pré-Configurados: Conjunto de prompts para operações comuns do Kafka
  • Compatibilidade: Funciona com modelos de LLM compatíveis com MCP

Começando

Pré-requisitos

  • Go 1.24 ou superior
  • Docker (para executar testes de integração)
  • Acesso a um cluster Kafka

Instalação

Homebrew (macOS e Linux)

A maneira mais fácil de instalar o kafka-mcp-server é usando Homebrew:

# Add the tap repository
brew tap tuannvm/mcp

# Install kafka-mcp-server
brew install kafka-mcp-server

Para atualizar para a versão mais recente:

brew update && brew upgrade kafka-mcp-server

A partir do Código Fonte

# Clone the repository
git clone https://github.com/tuannvm/kafka-mcp-server.git
cd kafka-mcp-server

# Build the server
go build -o kafka-mcp-server ./cmd

Integração com Clientes MCP

Este servidor MCP pode ser integrado com várias aplicações de IA. Abaixo estão as instruções específicas por plataforma:

Cursor

Edite ~/.cursor/mcp.json e adicione a configuração do kafka-mcp-server:

{
  "mcpServers": {
    "kafka": {
      "command": "kafka-mcp-server",
      "args": [],
      "env": {
        "KAFKA_BROKERS": "localhost:9092",
        "KAFKA_CLIENT_ID": "kafka-mcp-server",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Claude Desktop

Edite seu arquivo de configuração do Claude e adicione o servidor:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "kafka": {
      "command": "kafka-mcp-server",
      "args": [],
      "env": {
        "KAFKA_BROKERS": "localhost:9092",
        "KAFKA_CLIENT_ID": "kafka-mcp-server",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Reinicie o Claude Desktop para aplicar as alterações.

Claude Code

Para usar com Claude Code, adicione o servidor usando o comando de configuração MCP integrado:

# Add kafka-mcp-server with environment variables
claude mcp add kafka \
  --env KAFKA_BROKERS=localhost:9092 \
  --env KAFKA_CLIENT_ID=kafka-mcp-server \
  --env MCP_TRANSPORT=stdio \
  --env KAFKA_SASL_MECHANISM= \
  --env KAFKA_SASL_USER= \
  --env KAFKA_SASL_PASSWORD= \
  --env KAFKA_TLS_ENABLE=false \
  -- kafka-mcp-server

Outros comandos úteis:

# List configured MCP servers
claude mcp list

# Remove server
claude mcp remove kafka

# Test server connection
claude mcp get kafka

ChatWise

  1. Abra ChatWise → Configurações → Ferramentas → "+" → "Command Line MCP"
  2. Configure:
    • ID: kafka
    • Comando: kafka-mcp-server
    • Args: (deixe vazio)
    • Env: Adicione variáveis de ambiente: 
      KAFKA_BROKERS=localhost:9092
KAFKA_CLIENT_ID=kafka-mcp-server
MCP_TRANSPORT=stdio

Simplifique a Configuração com mcpenetes

Gerenciar configurações de servidores MCP em vários clientes pode se tornar desafiador. mcpenetes é uma ferramenta dedicada que torna esse processo significativamente mais fácil:

# Install mcpenetes
go install github.com/tuannvm/mcpenetes@latest

Principais Recursos

  • Busca Interativa: Encontre e selecione configurações do Kafka MCP Server com um comando simples
  • Aplicar em Todos os Lugares: Sincronize automaticamente as configurações em todos os seus clientes MCP
  • Backup de Configuração: Faça backup com segurança das configurações existentes antes de fazer alterações
  • Restauração: Reverta facilmente para configurações anteriores, se necessário

Início Rápido com mcpenetes

# Search for available MCP servers including kafka-mcp-server
mcpenetes search 

# Apply kafka-mcp-server configuration to all your clients at once
mcpenetes apply

# Load a configuration from your clipboard
mcpenetes load

Com o mcpenetes, você pode manter múltiplas configurações do Kafka (desenvolvimento, produção, etc.) e alternar entre elas instantaneamente em todos os seus clientes (Cursor, Claude Desktop, Windsurf, ChatWise) sem editar manualmente os arquivos de configuração de cada cliente.

Ferramentas MCP

O servidor expõe as seguintes ferramentas para interação com Kafka. Para documentação detalhada, incluindo exemplos e respostas de amostra, consulte docs/tools.md.

  • produce_message: Produz mensagens para tópicos do Kafka
  • consume_messages: Consome mensagens de tópicos do Kafka em operações em lote
  • list_brokers: Lista todos os endereços de brokers Kafka configurados
  • describe_topic: Fornece metadados abrangentes para tópicos específicos
  • list_consumer_groups: Enumera todos os grupos de consumidores no cluster
  • describe_consumer_group: Fornece informações detalhadas do grupo de consumidores, incluindo métricas de lag
  • describe_configs: Recupera configurações para recursos do Kafka
  • cluster_overview: Fornece resumos abrangentes de saúde do cluster
  • list_topics: Lista todos os tópicos com metadados, incluindo informações de partição e replicação

Recursos MCP

O servidor fornece os seguintes recursos que podem ser acessados através do protocolo MCP. Para documentação detalhada, incluindo respostas de exemplo, consulte docs/resources.md.

  • kafka-mcp://overview: Resumo abrangente de saúde do cluster
  • kafka-mcp://health-check: Avaliação detalhada de saúde com insights acionáveis
  • kafka-mcp://under-replicated-partitions: Análise de partições com problemas de replicação
  • kafka-mcp://consumer-lag-report: Análise de desempenho do consumidor com limites personalizáveis

Prompts MCP

O servidor inclui os seguintes prompts pré-configurados para operações e diagnósticos do Kafka. Para documentação detalhada, incluindo argumentos e respostas de exemplo, consulte docs/prompts.md.

  • kafka_cluster_overview: Gera resumos abrangentes de saúde do cluster
  • kafka_health_check: Realiza avaliações detalhadas de saúde com recomendações acionáveis
  • kafka_under_replicated_partitions: Analisa problemas de replicação com orientação de solução de problemas
  • kafka_consumer_lag_report: Fornece análise de lag do consumidor com recomendações de otimização de desempenho

Exemplo de Ponta a Ponta

Aqui está um exemplo de interação mostrando como um assistente de IA pode usar essas ferramentas para ajudar um usuário:

Consulta do Usuário: "Precisamos investigar por que nosso pipeline de processamento de pedidos está ficando para trás. Você pode me ajudar a verificar o lag do consumidor?"

Fluxo de trabalho do Assistente de IA:

  1. Primeiro, verifique os grupos de consumidores

    > Using list_consumer_groups tool
> Discovers "order-processor" group

  2. Em seguida, examine os detalhes do grupo de consumidores

    > Using describe_consumer_group tool with group_id "order-processor" and include_offsets=true
> Discovers lag on several partitions

  3. Obtenha a visão geral do cluster para verificar a saúde geral

    > Using cluster_overview tool
> Confirms no under-replicated partitions or offline brokers

  4. Gere um relatório de lag do consumidor

    > Using consumer_lag_report prompt with threshold=1000
> Provides detailed analysis of lag across consumer groups

  5. Forneça recomendações acionáveis:

    Based on my analysis, your order-processor consumer group has significant lag on topic orders, partitions 2 and 3, with lag values of 15,420 and 12,305 messages respectively.

The cluster itself is healthy with no under-replicated partitions, suggesting this is an issue with the consumer application rather than Kafka infrastructure.

I recommend:
1. Check the consumer instances processing those partitions for slowdowns or errors
2. Consider scaling up your consumer group by adding more instances
3. Review the consumer configuration, particularly max.poll.records and max.poll.interval.ms
4. Examine any processing bottlenecks in the consumer logic

Este fluxo de trabalho contínuo demonstra como as ferramentas Kafka MCP permitem que modelos de LLM realizem diagnósticos sofisticados e forneçam insights acionáveis.

Configuração

O servidor pode ser configurado usando as seguintes variáveis de ambiente:

VariávelDescriçãoPadrão
KAFKA_BROKERSLista separada por vírgulas de endereços de brokers Kafkalocalhost:9092
KAFKA_CLIENT_IDID do cliente Kafka usado para conexõeskafka-mcp-server
MCP_TRANSPORTMétodo de transporte MCP (stdio/http)stdio
KAFKA_SASL_MECHANISMMecanismo SASL: plain, scram-sha-256, scram-sha-512 ou "" (desabilitado)""
KAFKA_SASL_USERNome de usuário para autenticação SASL""
KAFKA_SASL_PASSWORDSenha para autenticação SASL""
KAFKA_TLS_ENABLEHabilitar TLS para conexão Kafka (true ou false)false
KAFKA_TLS_INSECURE_SKIP_VERIFYIgnorar verificação de certificado TLS (true ou false)false

Configuração OAuth 2.1 (Somente Transporte HTTP)

Ao usar transporte HTTP (MCP_TRANSPORT=http), a autenticação OAuth 2.1 pode ser habilitada:

VariávelDescriçãoPadrãoObrigatória
MCP_HTTP_PORTPorta do servidor HTTP8080Não
OAUTH_ENABLEDHabilitar autenticação OAuth 2.1falseNão
OAUTH_MODEModo OAuth: native ou proxynativeNão
OAUTH_PROVIDERProvedor: hmac, okta, google, azureoktaNão
OAUTH_SERVER_URLURL completa do servidor MCP (ex.: https://localhost:8080)-Quando OAuth habilitado
OIDC_ISSUERURL do emissor OAuth-Quando OAuth habilitado
OIDC_AUDIENCEAudiência OAuth-Quando OAuth habilitado
OIDC_CLIENT_IDID do cliente OAuth-Somente modo Proxy
OIDC_CLIENT_SECRETSegredo do cliente OAuth-Somente modo Proxy
OAUTH_REDIRECT_URISURIs de redirecionamento separados por vírgulas-Somente modo Proxy
JWT_SECRETSegredo de assinatura JWT-Somente modo Proxy

Para configuração detalhada de OAuth e exemplos, consulte docs/oauth.md.

Notas de Segurança:

  • Ao usar KAFKA_TLS_INSECURE_SKIP_VERIFY=true, o servidor ignorará a verificação de certificado TLS. Isso deve ser usado apenas em ambientes de desenvolvimento ou teste, ou ao usar certificados autoassinados.
  • OAuth está disponível apenas ao usar transporte HTTP. O transporte STDIO não suporta OAuth.
  • Sempre use HTTPS em produção quando OAuth estiver habilitado.

Considerações de Segurança

O servidor foi projetado com segurança de nível empresarial em mente:

  • Autenticação:
    • Kafka: Suporte completo para SASL PLAIN, SCRAM-SHA-256 e SCRAM-SHA-512
    • Servidor MCP: Autenticação OAuth 2.1 para transporte HTTP (Okta, Google, Azure AD, HMAC)
  • Criptografia: Suporte TLS para comunicação segura com brokers Kafka
  • Validação de Entrada: Validação completa de todas as entradas do usuário para prevenir ataques de injeção
  • Tratamento de Erros: Tratamento seguro de erros que não expõe informações sensíveis
  • Segurança de Tokens: Validação de tokens Bearer com cache de 5 minutos para endpoints protegidos por OAuth

Para práticas recomendadas de segurança OAuth, consulte docs/oauth.md.

Desenvolvimento

Testes

Cobertura abrangente de testes garante confiabilidade:

# Run all tests (requires Docker for integration tests)
go test ./...

# Run tests excluding integration tests
go test -short ./...

# Run integration tests with specific Kafka brokers
export KAFKA_BROKERS="your-broker:9092"
export SKIP_KAFKA_TESTS="false"
go test ./kafka -v -run Test

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.