Purpose
adx-mcp-server is a Model Context Protocol (MCP) server used to let AI assistants execute KQL queries and explore data in Azure Data Explorer (ADX/Kusto) databases through a standardized interface. The server can access Azure Data Explorer as well as Eventhouse clusters in Microsoft Fabric.
Main Capabilities
Query Execution
- Execute KQL queries: run arbitrary KQL queries against an ADX database
- Structured results: results are returned in JSON format for easy consumption
Database Discovery
- List tables: discover all tables in the database
- View schema: inspect table schemas and column types
- Sample data: preview table contents with a configurable sample size
- Table statistics: obtain detailed metadata including row counts and storage size
Authentication
- DefaultAzureCredential: supports Azure CLI, managed identity, etc.
- Workload Identity: native support for AKS workload identity
- Flexible credentials: compatible with multiple Azure authentication methods
Deployment Options
- Multiple transport methods: stdio (default), HTTP, and Server-Sent Events (SSE)
- Docker support: production-ready container images following security best practices
- Dev Container: seamless development experience through GitHub Codespaces
The tool list is configurable, and you can choose which tools to expose to MCP clients.
Usage
- Use Azure CLI to sign in to an Azure account with permissions on the ADX cluster.
- Configure the ADX cluster environment variables through a .env file or system environment variables.
- Add the server configuration to the client configuration file (for example, Claude Desktop).
When workload identity is configured in an AKS environment, the server uses WorkloadIdentityCredential by default. For AKS using Azure Workload Identity, simply:
- Ensure the Pod sets the AZURE_TENANT_ID and AZURE_CLIENT_ID environment variables
- Ensure the token file is mounted at the default path, or specify a custom path through ADX_TOKEN_FILE_PATH
If these environment variables do not exist, the server will automatically fall back to DefaultAzureCredential.
Docker
Build and run the Docker image. Run it after creating a .env file containing the ADX credentials.
When using the containerized server in Claude Desktop, update the configuration to use Docker and environment variables.
For HTTP mode deployment, the corresponding Docker configuration can be used.
Dev Container / GitHub Codespace
This repository can also be used as a development container. The Dev Container configuration is located in the devcontainer-feature/adx-mcp-server folder.
Development and Testing
The project uses uv to manage dependencies. You can create a virtual environment and install dependencies. The project uses a src directory structure and includes a comprehensive test suite, with tests run using pytest. The tests are divided into: configuration validation tests, server functionality tests, error handling tests, and main application tests.
Other Notes
Available tools, required environment variables, and optional environment variables are described in detail in the repository. Contributions are welcome, and suggestions or improvements can be submitted through issues or pull requests.
