adx-mcp-server
Servidor MCP de Azure Data Explorer
Un servidor de Protocolo de contexto de modelo (MCP) para Azure Data Explorer/Eventhouse en Microsoft Fabric.
Esto proporciona acceso a sus clústeres y bases de datos de Azure Data Explorer/Eventhouse a través de interfaces MCP estandarizadas, lo que permite que los asistentes de IA ejecuten consultas KQL y exploren sus datos.
Características
[x] Ejecutar consultas KQL en Azure Data Explorer
[x] Descubra y explore recursos de bases de datos
[x] Listar tablas en la base de datos configurada
[x] Ver esquemas de tablas
[x] Datos de muestra de tablas
[x] Obtener estadísticas/detalles de la tabla
[x] Soporte de autenticación
[x] Compatibilidad con credenciales de token (Azure CLI, MSI, etc.)
[x] Compatibilidad de credenciales de identidad de carga de trabajo para AKS
[x] Compatibilidad con contenedores Docker
[x] Proporcionar herramientas interactivas para asistentes de IA
La lista de herramientas es configurable, por lo que puede elegir qué herramientas quiere que estén disponibles para el cliente MCP. Esto resulta útil si no utiliza ciertas funciones o si no desea ocupar demasiado espacio en la ventana de contexto.
Related MCP server: EdgeLake MCP Server
Uso
Inicie sesión en su cuenta de Azure que tenga permiso para el clúster ADX mediante la CLI de Azure.
Configure las variables de entorno para su clúster ADX, ya sea a través de un archivo
.envo 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-tokenCompatibilidad con identidades de carga de trabajo de Azure
El servidor ahora usa WorkloadIdentityCredential de forma predeterminada al ejecutarse en entornos de Azure Kubernetes Service (AKS) con la identidad de la carga de trabajo configurada. Prioriza el uso de WorkloadIdentityCredential siempre que estén presentes las variables de entorno necesarias.
Para AKS con Azure Workload Identity, solo necesita:
Asegúrese de que el pod tenga configuradas las variables de entorno
AZURE_TENANT_IDyAZURE_CLIENT_IDAsegú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 varios métodos de autenticación en secuencia.
Agregue la configuración del servidor al archivo de configuración del 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 ENOENTen Claude Desktop, es posible que deba especificar la ruta completa auvo establecer la variable de entornoNO_UV=1en la configuración.
Uso de Docker
Este proyecto incluye soporte para Docker para una fácil implementación y aislamiento.
Construyendo la imagen de Docker
Construya la imagen de Docker usando:
docker build -t adx-mcp-server .Ejecutando con Docker
Puedes 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-serverUsando docker-compose:
Cree un archivo .env con sus credenciales de Azure Data Explorer y luego ejecute:
docker-compose upEjecutar con Docker en Claude Desktop
Para utilizar el servidor en contenedores 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 Docker utilizando el indicador -e con solo el nombre de la variable y proporcionando los valores reales en el objeto env .
Uso como contenedor de desarrollo / GitHub Codespace
Este repositorio también puede utilizarse 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 obtener más detalles, consulte el archivo README de devcontainer .
Desarrollo
¡Agradecemos sus contribuciones! Abra un problema o envíe una solicitud de incorporación de cambios si tiene alguna sugerencia o mejora.
Este proyecto utiliza uv para gestionar las dependencias. Instale uv siguiendo las instrucciones para su plataforma:
curl -LsSf https://astral.sh/uv/install.sh | shLuego 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 directorio 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 filePruebas
El proyecto incluye un conjunto de pruebas integral 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-missingLas pruebas se organizan en:
Pruebas de validación de configuración
Pruebas de funcionalidad del servidor
Pruebas de manejo de errores
Pruebas de aplicación principales
Al agregar nuevas funciones, agregue también las pruebas correspondientes.
Herramientas
Herramienta | Categoría | Descripción |
| Consulta | Ejecutar una consulta KQL en Azure Data Explorer |
| Descubrimiento | Listar todas las tablas en la base de datos configurada |
| Descubrimiento | Obtener el esquema para una tabla específica |
| Descubrimiento | Obtener datos de muestra de una tabla con tamaño de muestra opcional |
Licencia
Instituto Tecnológico de Massachusetts (MIT)
Available Tools
5 toolsexecute_queryB
Executes a Kusto Query Language (KQL) query against the configured Azure Data Explorer database and returns the results as a list of dictionaries.
Inputs: query (required). Returns: result
get_table_detailsC
Retrieves table details including TotalRowCount, HotExtentSize
Inputs: table_name (required). Returns: result
get_table_schemaB
Retrieves the schema information for a specified table in the Azure Data Explorer database, including column names, data types, and other schema-related metadata.
Inputs: table_name (required). Returns: result
list_tablesA
Retrieves a list of all tables available in the configured Azure Data Explorer database, including their names, folders, and database associations.
Inputs: no named parameters. Returns: result
sample_table_dataB
Retrieves a random sample of rows from the specified table in the Azure Data Explorer database. The sample_size parameter controls how many rows to return (default: 10).
Inputs: table_name (required), sample_size. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct purpose: listing tables, retrieving schema, retrieving details, sampling data, and executing arbitrary queries. No overlap and clear boundaries between tools.
All tool names follow a consistent verb_noun pattern (e.g., list_tables, get_table_schema, execute_query) using snake_case, making them predictable and easy to interpret.
Five tools is well-scoped for a read-only Azure Data Explorer query server, covering essential operations like listing, schema retrieval, details, sampling, and querying without unnecessary clutter.
The tool set provides a solid foundation for querying and metadata retrieval. Missing are data modification or ingestion tools, but for a query-focused server this is acceptable, though a bit more (e.g., table statistics) could enhance completeness.
Maintenance
Related MCP Connectors
Query, explore, and manage your databases through natural conversation.
Company and industrial data for AI assistants: datasets, SQL, dashboards, alarms, with approvals.
Query Postgres, MySQL, SQL Server, Oracle, BigQuery, ClickHouse and Redshift from your AI client.
Connect your AI assistants to Keboola and expose your data, transformations, SQL queries, ...
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables intelligent KQL query execution against Azure Data Explorer clusters with AI-powered schema caching and natural language to KQL conversion. Provides automated schema discovery and context-aware query assistance for enhanced data exploration.75 PyPI24MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to query and explore distributed data across EdgeLake nodes through SQL operations, resource discovery, and schema inspection. Supports complex queries with joins, aggregations, and metadata fields across multiple databases and tables.Mozilla Public 2.0
- AlicenseNot gradedqualityDmaintenanceEnables users to authenticate with Azure Data Explorer and execute KQL queries via natural language through the Model Context Protocol.547 npmMIT
- AlicenseAqualityBmaintenanceEnables AI assistants to query Azure Data Explorer using natural language, eliminating the need to write KQL.7459 npm8MIT