Azure Data Explorer MCP Server

1# Azure Data Explorer MCP Server
2 
3<a href="https://glama.ai/mcp/servers/1yysyd147h">
4  <img width="380" height="200" src="https://glama.ai/mcp/servers/1yysyd147h/badge" />
5</a>
6 
7[![CI](https://github.com/pab1it0/adx-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/pab1it0/adx-mcp-server/actions/workflows/ci.yml)
8[![codecov](https://codecov.io/gh/pab1it0/adx-mcp-server/branch/main/graph/badge.svg)](https://codecov.io/gh/pab1it0/adx-mcp-server)
9[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
11 
12A [Model Context Protocol][mcp] (MCP) server that enables AI assistants to execute KQL queries and explore Azure Data Explorer (ADX/Kusto) databases through standardized interfaces.
13 
14This server provides seamless access to Azure Data Explorer and Eventhouse (in Microsoft Fabric) clusters, allowing AI assistants to query and analyze your data using the powerful Kusto Query Language.
15 
16[mcp]: https://modelcontextprotocol.io
17 
18## Features
19 
20### Query Execution
21- **Execute KQL queries** - Run arbitrary KQL queries against your ADX database
22- **Structured results** - Get results formatted as JSON for easy consumption
23 
24### Database Discovery
25- **List tables** - Discover all tables in your database
26- **View schemas** - Inspect table schemas and column types
27- **Sample data** - Preview table contents with configurable sample sizes
28- **Table statistics** - Get detailed metadata including row counts and storage size
29 
30### Authentication
31- **DefaultAzureCredential** - Supports Azure CLI, Managed Identity, and more
32- **Workload Identity** - Native support for AKS workload identity
33- **Flexible credentials** - Works with multiple Azure authentication methods
34 
35### Deployment Options
36- **Multiple transports** - stdio (default), HTTP, and Server-Sent Events (SSE)
37- **Docker support** - Production-ready container images with security best practices
38- **Dev Container** - Seamless development experience with GitHub Codespaces
39 
40The list of tools is configurable, so you can choose which tools you want to make available to the MCP client. This is useful if you don't use certain functionality or if you don't want to take up too much of the context window.
41 
42## Usage
43 
441. Login to your Azure account which has the permission to the ADX cluster using Azure CLI.
45 
462. Configure the environment variables for your ADX cluster, either through a `.env` file or system environment variables:
47 
48```env
49# Required: Azure Data Explorer configuration
50ADX_CLUSTER_URL=https://yourcluster.region.kusto.windows.net
51ADX_DATABASE=your_database
52 
53# Optional: Azure Workload Identity credentials 
54# AZURE_TENANT_ID=your-tenant-id
55# AZURE_CLIENT_ID=your-client-id 
56# ADX_TOKEN_FILE_PATH=/var/run/secrets/azure/tokens/azure-identity-token
57 
58# Optional: Custom MCP Server configuration
59ADX_MCP_SERVER_TRANSPORT=stdio # Choose between http/sse/stdio, default = stdio
60 
61# Optional: Only relevant for non-stdio transports
62ADX_MCP_BIND_HOST=127.0.0.1 # default = 127.0.0.1
63ADX_MCP_BIND_PORT=8080 # default = 8080
64```
65 
66#### Azure Workload Identity Support
67 
68The server now uses WorkloadIdentityCredential by default when running in Azure Kubernetes Service (AKS) environments with workload identity configured. It prioritizes the use of WorkloadIdentityCredential whenever the necessary environment variables are present.
69 
70For AKS with Azure Workload Identity, you only need to:
711. Make sure the pod has `AZURE_TENANT_ID` and `AZURE_CLIENT_ID` environment variables set
722. Ensure the token file is mounted at the default path or specify a custom path with `ADX_TOKEN_FILE_PATH`
73 
74If these environment variables are not present, the server will automatically fall back to DefaultAzureCredential, which tries multiple authentication methods in sequence.
75 
763. Add the server configuration to your client configuration file. For example, for Claude Desktop:
77 
78```json
79{
80  "mcpServers": {
81    "adx": {
82      "command": "uv",
83      "args": [
84        "--directory",
85        "<full path to adx-mcp-server directory>",
86        "run",
87        "src/adx_mcp_server/main.py"
88      ],
89      "env": {
90        "ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
91        "ADX_DATABASE": "your_database"
92      }
93    }
94  }
95}
96```
97 
98> Note: if you see `Error: spawn uv ENOENT` in Claude Desktop, you may need to specify the full path to `uv` or set the environment variable `NO_UV=1` in the configuration.
99 
100## Docker Usage
101 
102This project includes Docker support for easy deployment and isolation.
103 
104### Building the Docker Image
105 
106Build the Docker image using:
107 
108```bash
109docker build -t adx-mcp-server .
110```
111 
112### Running with Docker
113 
114You can run the server using Docker in several ways:
115 
116#### Using docker run directly:
117 
118```bash
119docker run -it --rm \
120  -e ADX_CLUSTER_URL=https://yourcluster.region.kusto.windows.net \
121  -e ADX_DATABASE=your_database \
122  -e AZURE_TENANT_ID=your_tenant_id \
123  -e AZURE_CLIENT_ID=your_client_id \
124  adx-mcp-server
125```
126 
127#### Using docker-compose:
128 
129Create a `.env` file with your Azure Data Explorer credentials and then run:
130 
131```bash
132docker-compose up
133```
134 
135### Running with Docker in Claude Desktop
136 
137To use the containerized server with Claude Desktop, update the configuration to use Docker with the environment variables:
138 
139```json
140{
141  "mcpServers": {
142    "adx": {
143      "command": "docker",
144      "args": [
145        "run",
146        "--rm",
147        "-i",
148        "-e", "ADX_CLUSTER_URL",
149        "-e", "ADX_DATABASE",
150        "-e", "AZURE_TENANT_ID",
151        "-e", "AZURE_CLIENT_ID",
152        "-e", "ADX_TOKEN_FILE_PATH",
153        "adx-mcp-server"
154      ],
155      "env": {
156        "ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
157        "ADX_DATABASE": "your_database",
158        "AZURE_TENANT_ID": "your_tenant_id",
159        "AZURE_CLIENT_ID": "your_client_id",
160        "ADX_TOKEN_FILE_PATH": "/var/run/secrets/azure/tokens/azure-identity-token"
161      }
162    }
163  }
164}
165```
166 
167This configuration passes the environment variables from Claude Desktop to the Docker container by using the `-e` flag with just the variable name, and providing the actual values in the `env` object.
168 
169#### Using Docker with HTTP Transport
170 
171For HTTP mode deployment, you can use the following Docker configuration:
172 
173```json
174{
175  "mcpServers": {
176    "adx": {
177      "command": "docker",
178      "args": [
179        "run",
180        "--rm",
181        "-i",
182        "-p", "8080:8080",
183        "-e", "ADX_CLUSTER_URL",
184        "-e", "ADX_DATABASE", 
185        "-e", "ADX_MCP_SERVER_TRANSPORT",
186        "-e", "ADX_MCP_BIND_HOST",
187        "-e", "ADX_MCP_BIND_PORT",
188        "adx-mcp-server"
189      ],
190      "env": {
191        "ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
192        "ADX_DATABASE": "your_database",
193        "ADX_MCP_SERVER_TRANSPORT": "http",
194        "ADX_MCP_BIND_HOST": "0.0.0.0",
195        "ADX_MCP_BIND_PORT": "8080"
196      }
197    }
198  }
199}
200```
201 
202## Using as a Dev Container / GitHub Codespace
203 
204This repository can also be used as a development container for a seamless development experience. The dev container setup is located in the `devcontainer-feature/adx-mcp-server` folder.
205 
206For more details, check the [devcontainer README](devcontainer-feature/adx-mcp-server/README.md).
207 
208 
209 
210## Development
211 
212Contributions are welcome! Please open an issue or submit a pull request if you have any suggestions or improvements.
213 
214This project uses [`uv`](https://github.com/astral-sh/uv) to manage dependencies. Install `uv` following the instructions for your platform:
215 
216```bash
217curl -LsSf https://astral.sh/uv/install.sh | sh
218```
219 
220You can then create a virtual environment and install the dependencies with:
221 
222```bash
223uv venv
224source .venv/bin/activate  # On Unix/macOS
225.venv\Scripts\activate     # On Windows
226uv pip install -e .
227```
228 
229## Project Structure
230 
231The project has been organized with a `src` directory structure:
232 
233```
234adx-mcp-server/
235├── src/
236│   └── adx_mcp_server/
237│       ├── __init__.py      # Package initialization
238│       ├── server.py        # MCP server implementation
239│       ├── main.py          # Main application logic
240├── Dockerfile               # Docker configuration
241├── docker-compose.yml       # Docker Compose configuration
242├── .dockerignore            # Docker ignore file
243├── pyproject.toml           # Project configuration
244└── README.md                # This file
245```
246 
247### Testing
248 
249The project includes a comprehensive test suite that ensures functionality and helps prevent regressions.
250 
251Run the tests with pytest:
252 
253```bash
254# Install development dependencies
255uv pip install -e ".[dev]"
256 
257# Run the tests
258pytest
259 
260# Run with coverage report
261pytest --cov=src --cov-report=term-missing
262```
263Tests are organized into:
264 
265- Configuration validation tests
266- Server functionality tests
267- Error handling tests
268- Main application tests
269 
270When adding new features, please also add corresponding tests.
271 
272## Available Tools
273 
274| Tool | Category | Description | Parameters |
275|------|----------|-------------|------------|
276| `execute_query` | Query | Execute a KQL query against Azure Data Explorer | `query` (string) - KQL query to execute |
277| `list_tables` | Discovery | List all tables in the configured database | None |
278| `get_table_schema` | Discovery | Get the schema for a specific table | `table_name` (string) - Name of the table |
279| `sample_table_data` | Discovery | Get sample data from a table | `table_name` (string), `sample_size` (int, default: 10) |
280| `get_table_details` | Discovery | Get table statistics and metadata | `table_name` (string) - Name of the table |
281 
282## Configuration
283 
284### Required Environment Variables
285 
286| Variable | Description | Example |
287|----------|-------------|---------|
288| `ADX_CLUSTER_URL` | Azure Data Explorer cluster URL | `https://yourcluster.region.kusto.windows.net` |
289| `ADX_DATABASE` | Database name to connect to | `your_database` |
290 
291### Optional Environment Variables
292 
293#### Azure Workload Identity (for AKS)
294| Variable | Description | Default |
295|----------|-------------|---------|
296| `AZURE_TENANT_ID` | Azure AD tenant ID | - |
297| `AZURE_CLIENT_ID` | Azure AD client/application ID | - |
298| `ADX_TOKEN_FILE_PATH` | Path to workload identity token file | `/var/run/secrets/azure/tokens/azure-identity-token` |
299 
300#### MCP Server Configuration
301| Variable | Description | Default |
302|----------|-------------|---------|
303| `ADX_MCP_SERVER_TRANSPORT` | Transport mode: `stdio`, `http`, or `sse` | `stdio` |
304| `ADX_MCP_BIND_HOST` | Host to bind to (HTTP/SSE only) | `127.0.0.1` |
305| `ADX_MCP_BIND_PORT` | Port to bind to (HTTP/SSE only) | `8080` |
306 
307#### Logging
308| Variable | Description | Default |
309|----------|-------------|---------|
310| `LOG_LEVEL` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` |
311 
312 
313## License
314 
315MIT
316 
317---
318 
319[mcp]: https://modelcontextprotocol.io
320