Azure Data Explorer

Un servidor MCP para integrarse con Azure Data Explorer, permitiendo la consulta y gestión de datos.

Documentación

Azure Data Explorer MCP Servidor

Un servidor de Model Context Protocol (MCP) que permite a los asistentes de IA ejecutar consultas KQL y explorar bases de datos de Azure Data Explorer (ADX/Kusto) a través de interfaces estandarizadas.

Este servidor proporciona acceso sin interrupciones a los clústeres de Azure Data Explorer y Eventhouse (en Microsoft Fabric), permitiendo a los asistentes de IA consultar y analizar sus datos usando el potente lenguaje de consulta Kusto.

Características

Ejecución de consultas

Ejecutar consultas KQL - Ejecutar consultas KQL arbitrarias contra su base de datos ADX
Resultados estructurados - Obtener resultados formateados como JSON para un consumo fácil

Descubrimiento de bases de datos

Listar tablas - Descubrir todas las tablas en su base de datos
Ver esquemas - Inspeccionar esquemas de tablas y tipos de columnas
Datos de muestra - Vista previa del contenido de la tabla con tamaños de muestra configurables
Estadísticas de tabla - Obtener metadatos detallados, incluidos recuentos de filas y tamaño de almacenamiento

Autenticación

DefaultAzureCredential - Admite Azure CLI, Managed Identity y más
Workload Identity - Soporte nativo para la identidad de carga de trabajo de AKS
Credenciales flexibles - Funciona con múltiples métodos de autenticación de Azure

Opciones de implementación

Múltiples transportes - stdio (predeterminado), HTTP y Server-Sent Events (SSE)
Soporte de Docker - Imágenes de contenedor listas para producción con mejores prácticas de seguridad
Contenedor de desarrollo - Experiencia de desarrollo fluida con GitHub Codespaces

La lista de herramientas es configurable, por lo que puede elegir qué herramientas desea poner a disposición del cliente MCP. Esto es útil si no utiliza cierta funcionalidad o si no desea ocupar demasiado espacio en la ventana de contexto.

Uso

Inicie sesión en su cuenta de Azure que tenga permiso para el clúster ADX usando Azure CLI.
Configure las variables de entorno para su clúster ADX, ya sea a través de un archivo .env o variables de entorno del 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

Soporte de Azure Workload Identity

El servidor ahora usa WorkloadIdentityCredential de forma predeterminada cuando se ejecuta en entornos de Azure Kubernetes Service (AKS) con identidad de carga de trabajo configurada. Prioriza el uso de WorkloadIdentityCredential siempre que las variables de entorno necesarias estén presentes.

Para AKS con Azure Workload Identity, solo necesita:

Asegúrese de que el pod tenga configuradas las variables de entorno AZURE_TENANT_ID y AZURE_CLIENT_ID
Asegúrese de que el archivo de token esté montado en la ruta predeterminada o especifique una ruta personalizada con ADX_TOKEN_FILE_PATH

Si estas variables de entorno no están presentes, el servidor recurrirá automáticamente a DefaultAzureCredential, que prueba múltiples métodos de autenticación en secuencia.

Agregue la configuración del servidor a su archivo de configuración de cliente. Por ejemplo, para 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: si ve Error: spawn uv ENOENT en Claude Desktop, es posible que deba especificar la ruta completa a uv o configurar la variable de entorno NO_UV=1 en la configuración.

Uso de Docker

Este proyecto incluye soporte de Docker para facilitar la implementación y el aislamiento.

Construcción de la imagen de Docker

Construya la imagen de Docker usando:

docker build -t adx-mcp-server .

Ejecución con Docker

Puede ejecutar el servidor usando Docker de varias maneras:

Usando docker run directamente:

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:

Cree un archivo .env con sus credenciales de Azure Data Explorer y luego ejecute:

docker-compose up

Ejecución con Docker en Claude Desktop

Para usar el servidor contenedorizado con Claude Desktop, actualice la configuración para usar Docker con las variables de entorno:

{
  "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"
      }
    }
  }
}

Esta configuración pasa las variables de entorno de Claude Desktop al contenedor de Docker usando la bandera -e con solo el nombre de la variable, y proporcionando los valores reales en el objeto env.

Uso de Docker con transporte HTTP

Para la implementación en modo HTTP, puede usar la siguiente configuración de 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"
      }
    }
  }
}

Uso como contenedor de desarrollo / GitHub Codespace

Este repositorio también se puede usar como contenedor de desarrollo para una experiencia de desarrollo fluida. La configuración del contenedor de desarrollo se encuentra en la carpeta devcontainer-feature/adx-mcp-server.

Para más detalles, consulte el README de devcontainer.

Desarrollo

¡Las contribuciones son bienvenidas! Abra un problema o envíe una solicitud de extracción si tiene sugerencias o mejoras.

Este proyecto usa uv para gestionar dependencias. Instale uv siguiendo las instrucciones para su plataforma:

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

Luego puede crear un entorno virtual e instalar las dependencias con:

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

Estructura del proyecto

El proyecto se ha organizado con una estructura de directorios 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

Pruebas

El proyecto incluye un conjunto de pruebas completo que garantiza la funcionalidad y ayuda a prevenir regresiones.

Ejecute las pruebas con pytest:

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

# Run the tests
pytest

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

Las pruebas están organizadas en:

Pruebas de validación de configuración
Pruebas de funcionalidad del servidor
Pruebas de manejo de errores
Pruebas de la aplicación principal

Al agregar nuevas funciones, agregue también las pruebas correspondientes.

Herramientas disponibles

Herramienta	Categoría	Descripción	Parámetros
`execute_query`	Consulta	Ejecutar una consulta KQL contra Azure Data Explorer	`query` (string) - Consulta KQL a ejecutar
`list_tables`	Descubrimiento	Listar todas las tablas en la base de datos configurada	Ninguno
`get_table_schema`	Descubrimiento	Obtener el esquema de una tabla específica	`table_name` (string) - Nombre de la tabla
`sample_table_data`	Descubrimiento	Obtener datos de muestra de una tabla	`table_name` (string), `sample_size` (int, predeterminado: 10)
`get_table_details`	Descubrimiento	Obtener estadísticas y metadatos de la tabla	`table_name` (string) - Nombre de la tabla

Configuración

Variables de entorno requeridas

Variable	Descripción	Ejemplo
`ADX_CLUSTER_URL`	URL del clúster de Azure Data Explorer	`https://yourcluster.region.kusto.windows.net`
`ADX_DATABASE`	Nombre de la base de datos a la que conectarse	`your_database`

Variables de entorno opcionales

Azure Workload Identity (para AKS)

Variable	Descripción	Predeterminado
`AZURE_TENANT_ID`	ID de inquilino de Azure AD	-
`AZURE_CLIENT_ID`	ID de cliente/aplicación de Azure AD	-
`ADX_TOKEN_FILE_PATH`	Ruta al archivo de token de identidad de carga de trabajo	`/var/run/secrets/azure/tokens/azure-identity-token`

Configuración del servidor MCP

Variable	Descripción	Predeterminado
`ADX_MCP_SERVER_TRANSPORT`	Modo de transporte: `stdio`, `http` o `sse`	`stdio`
`ADX_MCP_BIND_HOST`	Host al que vincularse (solo HTTP/SSE)	`127.0.0.1`
`ADX_MCP_BIND_PORT`	Puerto al que vincularse (solo HTTP/SSE)	`8080`

Registro

Variable	Descripción	Predeterminado
`LOG_LEVEL`	Nivel de registro: `DEBUG`, `INFO`, `WARNING`, `ERROR`	`INFO`

Licencia

MIT