Servidor MCP Azure Data Explorer | Awesome MCP Servers

Servidor MCP do Azure Data Explorer

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA executem consultas KQL e explorem bancos de dados do Azure Data Explorer (ADX/Kusto) por meio de interfaces padronizadas.

Este servidor fornece acesso contínuo aos clusters do Azure Data Explorer e Eventhouse (no Microsoft Fabric), permitindo que assistentes de IA consultem e analisem seus dados usando a poderosa Kusto Query Language.

Recursos

Execução de Consultas

Execute consultas KQL - Execute consultas KQL arbitrárias no seu banco de dados ADX
Resultados estruturados - Obtenha resultados formatados como JSON para fácil consumo

Descoberta de Banco de Dados

Listar tabelas - Descubra todas as tabelas no seu banco de dados
Ver esquemas - Inspecione esquemas de tabelas e tipos de colunas
Dados de amostra - Visualize o conteúdo das tabelas com tamanhos de amostra configuráveis
Estatísticas de tabela - Obtenha metadados detalhados, incluindo contagens de linhas e tamanho de armazenamento

Autenticação

DefaultAzureCredential - Suporta Azure CLI, Identidade Gerenciada e mais
Workload Identity - Suporte nativo para identidade de carga de trabalho do AKS
Credenciais flexíveis - Funciona com vários métodos de autenticação do Azure

Opções de Implantação

Múltiplos transportes - stdio (padrão), HTTP e Server-Sent Events (SSE)
Suporte a Docker - Imagens de contêiner prontas para produção com práticas recomendadas de segurança
Dev Container - Experiência de desenvolvimento contínua com GitHub Codespaces

A lista de ferramentas é configurável, para que você possa escolher quais ferramentas deseja disponibilizar ao cliente MCP. Isso é útil se você não usa determinada funcionalidade ou se não quer ocupar muito espaço na janela de contexto.

Uso

Faça login na sua conta do Azure que tem permissão para o cluster ADX usando o Azure CLI.
Configure as variáveis de ambiente para o seu cluster ADX, seja por meio de um arquivo .env ou variáveis de ambiente do sistema:

# Required: Azure Data Explorer configuration
ADX_CLUSTER_URL=https://yourcluster.region.kusto.windows.net
ADX_DATABASE=your_database

# Optional: Azure Workload Identity credentials 
# AZURE_TENANT_ID=your-tenant-id
# AZURE_CLIENT_ID=your-client-id 
# ADX_TOKEN_FILE_PATH=/var/run/secrets/azure/tokens/azure-identity-token

# Optional: Custom MCP Server configuration
ADX_MCP_SERVER_TRANSPORT=stdio # Choose between http/sse/stdio, default = stdio

# Optional: Only relevant for non-stdio transports
ADX_MCP_BIND_HOST=127.0.0.1 # default = 127.0.0.1
ADX_MCP_BIND_PORT=8080 # default = 8080

Suporte ao Azure Workload Identity

O servidor agora usa WorkloadIdentityCredential por padrão quando executado em ambientes do Azure Kubernetes Service (AKS) com identidade de carga de trabalho configurada. Ele prioriza o uso de WorkloadIdentityCredential sempre que as variáveis de ambiente necessárias estiverem presentes.

Para AKS com Azure Workload Identity, você só precisa de:

Certifique-se de que o pod tenha as variáveis de ambiente AZURE_TENANT_ID e AZURE_CLIENT_ID definidas
Garanta que o arquivo de token esteja montado no caminho padrão ou especifique um caminho personalizado com ADX_TOKEN_FILE_PATH

Se essas variáveis de ambiente não estiverem presentes, o servidor usará automaticamente o DefaultAzureCredential, que tenta vários métodos de autenticação em sequência.

Adicione a configuração do servidor ao seu arquivo de configuração do cliente. Por exemplo, para o Claude Desktop:

{
  "mcpServers": {
    "adx": {
      "command": "uv",
      "args": [
        "--directory",
        "<full path to adx-mcp-server directory>",
        "run",
        "src/adx_mcp_server/main.py"
      ],
      "env": {
        "ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
        "ADX_DATABASE": "your_database"
      }
    }
  }
}

Nota: se você vir Error: spawn uv ENOENT no Claude Desktop, talvez seja necessário especificar o caminho completo para uv ou definir a variável de ambiente NO_UV=1 na configuração.

Uso com Docker

Este projeto inclui suporte a Docker para implantação e isolamento fáceis.

Construindo a Imagem Docker

Construa a imagem Docker usando:

docker build -t adx-mcp-server .

Executando com Docker

Você pode executar o servidor usando Docker de várias maneiras:

Usando docker run diretamente:

docker run -it --rm \
  -e ADX_CLUSTER_URL=https://yourcluster.region.kusto.windows.net \
  -e ADX_DATABASE=your_database \
  -e AZURE_TENANT_ID=your_tenant_id \
  -e AZURE_CLIENT_ID=your_client_id \
  adx-mcp-server

Usando docker-compose:

Crie um arquivo .env com suas credenciais do Azure Data Explorer e depois execute:

docker-compose up

Executando com Docker no Claude Desktop

Para usar o servidor em contêiner com o Claude Desktop, atualize a configuração para usar Docker com as variáveis de ambiente:

{
  "mcpServers": {
    "adx": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ADX_CLUSTER_URL",
        "-e", "ADX_DATABASE",
        "-e", "AZURE_TENANT_ID",
        "-e", "AZURE_CLIENT_ID",
        "-e", "ADX_TOKEN_FILE_PATH",
        "adx-mcp-server"
      ],
      "env": {
        "ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
        "ADX_DATABASE": "your_database",
        "AZURE_TENANT_ID": "your_tenant_id",
        "AZURE_CLIENT_ID": "your_client_id",
        "ADX_TOKEN_FILE_PATH": "/var/run/secrets/azure/tokens/azure-identity-token"
      }
    }
  }
}

Essa configuração passa as variáveis de ambiente do Claude Desktop para o contêiner Docker usando a flag -e apenas com o nome da variável e fornecendo os valores reais no objeto env.

Usando Docker com Transporte HTTP

Para implantação no modo HTTP, você pode usar a seguinte configuração Docker:

{
  "mcpServers": {
    "adx": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-p", "8080:8080",
        "-e", "ADX_CLUSTER_URL",
        "-e", "ADX_DATABASE", 
        "-e", "ADX_MCP_SERVER_TRANSPORT",
        "-e", "ADX_MCP_BIND_HOST",
        "-e", "ADX_MCP_BIND_PORT",
        "adx-mcp-server"
      ],
      "env": {
        "ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
        "ADX_DATABASE": "your_database",
        "ADX_MCP_SERVER_TRANSPORT": "http",
        "ADX_MCP_BIND_HOST": "0.0.0.0",
        "ADX_MCP_BIND_PORT": "8080"
      }
    }
  }
}

Usando como Dev Container / GitHub Codespace

Este repositório também pode ser usado como um contêiner de desenvolvimento para uma experiência de desenvolvimento contínua. A configuração do contêiner de desenvolvimento está localizada na pasta devcontainer-feature/adx-mcp-server.

Para mais detalhes, consulte o README do devcontainer.

Desenvolvimento

Contribuições são bem-vindas! Abra uma issue ou envie um pull request se tiver sugestões ou melhorias.

Este projeto usa uv para gerenciar dependências. Instale o uv seguindo as instruções para sua plataforma:

curl -LsSf https://astral.sh/uv/install.sh | sh

Você pode então criar um ambiente virtual e instalar as dependências com:

uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows
uv pip install -e .

Estrutura do Projeto

O projeto foi organizado com uma estrutura de diretórios src:

adx-mcp-server/
├── src/
│   └── adx_mcp_server/
│       ├── __init__.py      # Package initialization
│       ├── server.py        # MCP server implementation
│       ├── main.py          # Main application logic
├── Dockerfile               # Docker configuration
├── docker-compose.yml       # Docker Compose configuration
├── .dockerignore            # Docker ignore file
├── pyproject.toml           # Project configuration
└── README.md                # This file

Testes

O projeto inclui uma suíte de testes abrangente que garante a funcionalidade e ajuda a prevenir regressões.

Execute os testes com pytest:

# Install development dependencies
uv pip install -e ".[dev]"

# Run the tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=term-missing

Os testes são organizados em:

Testes de validação de configuração
Testes de funcionalidade do servidor
Testes de tratamento de erros
Testes do aplicativo principal

Ao adicionar novos recursos, adicione também os testes correspondentes.

Ferramentas Disponíveis

Ferramenta	Categoria	Descrição	Parâmetros
`execute_query`	Consulta	Execute uma consulta KQL no Azure Data Explorer	`query` (string) - Consulta KQL a ser executada
`list_tables`	Descoberta	Liste todas as tabelas no banco de dados configurado	Nenhum
`get_table_schema`	Descoberta	Obtenha o esquema de uma tabela específica	`table_name` (string) - Nome da tabela
`sample_table_data`	Descoberta	Obtenha dados de amostra de uma tabela	`table_name` (string), `sample_size` (int, padrão: 10)
`get_table_details`	Descoberta	Obtenha estatísticas e metadados da tabela	`table_name` (string) - Nome da tabela

Configuração

Variáveis de Ambiente Obrigatórias

Variável	Descrição	Exemplo
`ADX_CLUSTER_URL`	URL do cluster do Azure Data Explorer	`https://yourcluster.region.kusto.windows.net`
`ADX_DATABASE`	Nome do banco de dados para conectar	`your_database`

Variáveis de Ambiente Opcionais

Azure Workload Identity (para AKS)

Variável	Descrição	Padrão
`AZURE_TENANT_ID`	ID do locatário do Azure AD	-
`AZURE_CLIENT_ID`	ID do cliente/aplicativo do Azure AD	-
`ADX_TOKEN_FILE_PATH`	Caminho para o arquivo de token de identidade de carga de trabalho	`/var/run/secrets/azure/tokens/azure-identity-token`

Configuração do Servidor MCP

Variável	Descrição	Padrão
`ADX_MCP_SERVER_TRANSPORT`	Modo de transporte: `stdio`, `http` ou `sse`	`stdio`
`ADX_MCP_BIND_HOST`	Host para vincular (somente HTTP/SSE)	`127.0.0.1`
`ADX_MCP_BIND_PORT`	Porta para vincular (somente HTTP/SSE)	`8080`

Registro em Log

Variável	Descrição	Padrão
`LOG_LEVEL`	Nível de registro: `DEBUG`, `INFO`, `WARNING`, `ERROR`	`INFO`

Licença

MIT

Azure Data Explorer

Documentação