Kusto MCP Server

Um servidor MCP para Azure Data Explorer (Kusto) que permite que assistentes de IA interajam com bancos de dados Kusto.

GitHub
7
Experimente este MCPPatrocinado

Documentação

🔍 Kusto MCP Server

CI npm version npm downloads

Transforme seu assistente de IA em um analista de dados em 2 minutos.

Conecte Cline, Cursor, Claude Desktop ou qualquer ferramenta de IA ao Azure Data Explorer. Faça perguntas em inglês simples, obtenha insights dos seus dados instantaneamente - sem necessidade de conhecimento em KQL.

O que você pode fazer

  • "Mostre-me logs de erro da última hora" → Obtenha insights instantâneos de dados de telemetria
  • "Quais clientes geraram mais receita este mês?" → Analise métricas de negócios sem esforço
  • "Encontre todas as tentativas de autenticação falhas" → Investigue incidentes de segurança com ajuda de IA
  • "Resuma as tendências de desempenho do sistema" → Obtenha análise automatizada de dados de monitoramento

Chega de escrever consultas KQL complexas. Basta fazer perguntas naturais ao seu assistente de IA sobre seus dados.

Configuração rápida

Para usuários do Claude Code

Execute este comando no terminal para instalar:

claude mcp add kusto-mcp -- npx -y kusto-mcp@latest

Para usuários do Cline

Adicione isto ao seu arquivo cline_mcp_settings.json:

{
  "mcpServers": {
    "github.com/johnib/kusto-mcp": {
      "command": "npx",
      "args": ["-y", "kusto-mcp@latest"],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "initialize-connection",
        "show-tables",
        "show-table",
        "execute-query",
        "report-issue"
      ]
    }
  }
}

Para usuários do Cursor

Adicione isto ao seu VS Code settings.json:

{
  "mcp": {
    "servers": {
      "github.com/johnib/kusto-mcp": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "kusto-mcp"]
      }
    }
  }
}

Para usuários do Claude Desktop

Adicione isto ao seu arquivo de configuração do Claude Desktop:

{
  "mcpServers": {
    "kusto-mcp": {
      "command": "npx",
      "args": ["-y", "kusto-mcp"]
    }
  }
}

Configuração de autenticação

  1. Instale a CLI do Azure (se ainda não tiver):

    # Windows
winget install Microsoft.AzureCLI

# macOS
brew install azure-cli

# Linux
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

  2. Faça login no Azure:

    az login

  3. Pronto! Seu assistente de IA agora pode se conectar aos seus clusters do Azure Data Explorer.

Teste se funciona

Pergunte ao seu assistente de IA:

"Conecte-se ao meu cluster do Azure Data Explorer em https://your-cluster.kusto.windows.net e mostre-me as tabelas disponíveis"

Você deve ver seu assistente de IA conectar-se com sucesso e listar as tabelas do seu banco de dados.

Ferramentas de IA suportadas

  • ✅ Claude Code - Configuração com um comando e suporte nativo a MCP
  • ✅ Cline - Suporte completo com aprovação automática
  • ✅ Cursor - Integração completa
  • ✅ Claude Desktop - Suporte nativo a MCP
  • ✅ VS Code com MCP - Compatibilidade integrada
  • ✅ Qualquer ferramenta compatível com MCP - Suporte universal

Problemas comuns

🔒 Permissão negada?

  • Execute az login e verifique se você tem acesso ao cluster do Azure Data Explorer
  • Verifique se você está conectado ao locatário correto do Azure

🔌 Não consegue se conectar ao cluster?

  • Verifique novamente o formato da URL do cluster: https://your-cluster.kusto.windows.net
  • Garanta que o cluster esteja acessível a partir da sua rede

❓ A IA não vê as ferramentas?

  • Reinicie seu assistente de IA após adicionar a configuração
  • Verifique se a configuração JSON é válida (use um validador JSON)

Ainda com problemas? → Abra um problema ou consulte nosso guia de solução de problemas.

O que está por baixo dos panos

Este servidor MCP fornece ao seu assistente de IA ferramentas para:

  • Inicializar conexões com clusters do Azure Data Explorer
  • Navegar por tabelas e esquemas de banco de dados
  • Executar consultas KQL com limitação inteligente de resultados
  • Gerenciar autenticação com segurança por meio da CLI do Azure
  • Reportar um bug ou solicitar um recurso no GitHub (report-issue)

Os resultados são formatados e dimensionados automaticamente para as janelas de contexto da IA, para que seu assistente obtenha os dados necessários sem ficar sobrecarregado.

Reportando um problema

Encontrou um bug ou quer um recurso? Peça ao seu assistente de IA para "reportar um problema kusto-mcp sobre …" e ele chamará a ferramenta report-issue.

A ferramenta retorna um link de problema do GitHub pré-preenchido — abra-o em um navegador onde você está conectado ao GitHub, revise o título e o corpo e clique em Enviar novo problema. Algumas coisas que vale a pena saber:

  • Nenhum token do GitHub é necessário ou armazenado. O servidor nunca registra nada em seu nome; o problema é criado na sua própria conta do GitHub quando você envia o formulário. (Você precisa de uma conta do GitHub para enviar.)

  • Funciona mesmo quando a conexão está quebrada — não requer uma conexão Kusto ativa, então é a ferramenta certa para relatar problemas de conexão.

  • Por padrão, um rodapé de ambiente pequeno e não sensível (versões de kusto-mcp/Node/OS/cliente MCP, se uma conexão está ativa, formato de resposta, modo de gravação) é anexado para ajudar na triagem. Passe includeDiagnostics: false para omiti-lo. Ele nunca inclui sua URL de cluster, banco de dados, identidade, texto de consulta ou resultados.

Telemetria e Privacidade

O kusto-mcp relata telemetria de uso anônima para a instância Honeycomb do mantenedor para entender como a ferramenta é usada e diagnosticar falhas. A telemetria está sempre ativada — usar o kusto-mcp significa relatar uso anônimo. Não há dados pessoais ou organizacionais nela, nem texto de consulta ou resultados (detalhes abaixo).

O que é coletado (rastros, métricas e logs operacionais via OpenTelemetry):

  • Uso: quais ferramentas são chamadas, latência, comprimento de consulta/comando (não texto), contagens de linhas de resultado, tamanhos de resposta, resultados e suas configurações de config/flags de recurso.

  • Confiabilidade: contagens de chamadas/erros, tentativas/falhas de conexão e nomes de classes de erro (por exemplo, KustoQueryError) — nunca mensagens de erro.

  • Contadores de coorte: hashes com sal do seu ID de locatário do Azure (company_hash) e ID de objeto (user_hash), para que o mantenedor possa contar organizações e usuários distintos — nenhum locatário bruto, nome de empresa, domínio de e-mail, e-mail, UPN ou ID de usuário é enviado. Além disso, principal_type (usuário vs principal de serviço) e account_type (pessoal vs empresarial); o locatário compartilhado de conta pessoal não envia company_hash.

  • Ambiente: versão do kusto-mcp, SO/arquitetura, versão do Node.js, nome do cliente MCP e um identificador aleatório por instalação (machine.id).

O que NUNCA é coletado: nenhum nome de empresa ou domínio de e-mail; nenhum ID de locatário ou ID de usuário bruto do Azure; nenhum e-mail completo, UPN ou nome; nenhum nome de cluster, banco de dados, tabela ou função; nenhum texto de consulta, resultados, mensagens de erro, credenciais ou tokens.

Roteamento para seu próprio coletor: empresas que executam seu próprio pipeline OpenTelemetry podem redirecionar os dados com variáveis de ambiente padrão — OTEL_EXPORTER_OTLP_ENDPOINT (sua URL base HTTP OTLP) e OTEL_EXPORTER_OTLP_HEADERS (key=value,key2=value2).

Configuração avançada

Precisa de configurações personalizadas? Consulte nosso Guia de Configuração para:

  • Opções de formato de resposta (JSON vs Markdown)
  • Configurações de tempo limite de consulta
  • Limitação de tamanho de resultado
  • Integração com OpenTelemetry

Para desenvolvedores

Construindo, testando ou contribuindo? Consulte nossa Documentação para Desenvolvedores para:

  • Compilar a partir do código-fonte
  • Executar testes
  • Estrutura do projeto
  • Diretrizes de contribuição

Licença

MIT

💡 Dica profissional: Comece pedindo à sua IA para "mostrar as tabelas do meu banco de dados" para explorar quais dados você tem disponíveis e, em seguida, faça perguntas em linguagem natural sobre tabelas específicas.