You run an MCP server that lets AI assistants execute KQL queries against Azure Data Explorer databases and explore data using structured results. This server handles authentication, supports multiple transports, and can be deployed locally or in containers to suit your workflow.

How to use

To use the Azure Data Explorer MCP Server, start by authenticating to Azure and configuring your ADX connection details. Then launch the MCP server as a local process and connect your MCP client to the local endpoint. Once connected, you can execute KQL queries, list tables, inspect schemas, preview data, and retrieve table statistics through the MCP client.

How to install

Prerequisites you need before installing the MCP server.

• 1. Ensure you have Python installed on your system.
• 2. Install the MCP tooling used to run the server. The recommended tool for development and running the MCP server is available via a shell script. Use the following command to install it:
• 3. Install the MCP server dependencies and run the server as described in the steps below.

Install steps

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

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

Run the MCP server locally (stdio)

uv --directory <full path to adx-mcp-server directory> run src/adx_mcp_server/main.py

This starts the MCP server in stdio mode. You can then configure your MCP client to connect to the local process using the standard MCP client setup. If you see an issue like Error: spawn uv ENOENT, provide the full path to uv or set NO_UV=1 in the client configuration.

## Docker usage

You can run the MCP server in a container. Build the image, then run it with the required environment variables.

docker build -t adx-mcp-server .

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

If you prefer using the client configuration for Docker, you can use a similar setup in Claude Desktop by providing the environment variables and using a container runtime as shown in the examples above.

Dev container / Codespace

You can also develop and test inside a development container. The development container setup is organized under the devcontainer features path and is designed to give you a seamless development experience.

# Development container usage is configured in the devcontainer setup
# No additional commands are required here beyond the standard container workflow

Redirect to the dev container guide for full steps if you are using Codespaces or a local Codespace-like environment.

## Configuration and environment variables

Before starting, provide the Azure Data Explorer credentials as environment variables. The essential values are the cluster URL and the target database. Optional Azure Workload Identity credentials can also be supplied.

ADX_CLUSTER_URL=https://yourcluster.region.kusto.windows.net ADX_DATABASE=your_database

Optional (AKS workload identity)

AZURE_TENANT_ID=your-tenant-id AZURE_CLIENT_ID=your-client-id ADX_TOKEN_FILE_PATH=/var/run/secrets/azure/tokens/azure-identity-token

MCP server transport (stdio is default; other transports can be configured if needed)

ADX_MCP_SERVER_TRANSPORT=stdio

## Troubleshooting

If you encounter issues starting the server, check the following common problems and fixes.

- Make sure the environment variables are set correctly and the Azure credentials are valid.
- If EnOENT errors occur when starting via uv, provide the full path to uv or set NO\_UV=1 in the client configuration.
- Verify that the ADX cluster URL and database names are correct and reachable from the host or container.
- Confirm the correct Python environment is active when installing and running the server.

## Available tools

### execute\_query

Execute a KQL query against Azure Data Explorer and receive results in JSON.

### list\_tables

List all tables in the configured database.

### get\_table\_schema

Get the schema for a specific table, including column types.

### sample\_table\_data

Get a sample of table data with a configurable sample size.

### get\_table\_details

Get table statistics and metadata such as row counts and storage size.