📌Overview

Purpose: To provide a Model Context Protocol (MCP) server for Azure Data Explorer, enabling AI assistants to execute KQL queries and explore data seamlessly.

Overview: This framework offers standardized MCP interfaces for accessing Azure Data Explorer clusters and databases, facilitating interaction via KQL queries, data exploration, and secure access through token authentication.

Key Features:

Execute KQL Queries: Enables the execution of KQL queries against Azure Data Explorer, facilitating in-depth data analysis.
Resource Discovery: Allows users to discover database resources by listing tables, viewing schemas, and sampling data from the tables for effective data management.
Authentication Support: Provides token credential support for secure access via Azure CLI and Managed Service Identity (MSI), ensuring secure integration with Azure services.
Docker Containerization: Supports easy deployment and isolation through Docker, simplifying the server setup and scaling.
Configurable Tools for AI Assistants: Offers interactive tools with configurable functionalities, optimizing the context window usage based on user preferences.

Azure Data Explorer MCP Server

A Model Context Protocol (MCP) server for Azure Data Explorer/Eventhouse in Microsoft Fabric.

This provides access to your Azure Data Explorer/Eventhouse clusters and databases through standardized MCP interfaces, allowing AI assistants to execute KQL queries and explore your data.

More about MCP: https://modelcontextprotocol.io

Features

Execute KQL queries against Azure Data Explorer
Discover and explore database resources
- List tables in the configured database
- View table schemas
- Sample data from tables
- Get table statistics/details
Authentication support
- Token credential support (Azure CLI, MSI, etc.)
Docker containerization support
Provide interactive tools for AI assistants

The list of tools is configurable, so you can choose which tools to make available to the MCP client.

Usage

Login to your Azure account which has permission to the ADX cluster using Azure CLI.
Configure the environment variables for your ADX cluster, either through a .env file or system environment variables:

# Required: Azure Data Explorer configuration
ADX_CLUSTER_URL=https://yourcluster.region.kusto.windows.net
ADX_DATABASE=your_database

Add the server configuration to your client configuration file. For example, for 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"
      }
    }
  }
}

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.

Docker Usage

This project includes Docker support for easy deployment and isolation.

Building the Docker Image

Build the Docker image with:

docker build -t adx-mcp-server .

Running with Docker

Run the server using Docker:

docker run -it --rm \
  -e ADX_CLUSTER_URL=https://yourcluster.region.kusto.windows.net \
  -e ADX_DATABASE=your_database \
  adx-mcp-server

Or using docker-compose:

Create a .env file with your Azure Data Explorer credentials and run:

docker-compose up

Running with Docker in Claude Desktop

Configure Claude Desktop to use Docker with environment variables:

{
  "mcpServers": {
    "adx": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ADX_CLUSTER_URL",
        "-e", "ADX_DATABASE",
        "adx-mcp-server"
      ],
      "env": {
        "ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
        "ADX_DATABASE": "your_database"
      }
    }
  }
}

Development Container / GitHub Codespace

This repository can 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.

Refer to the devcontainer README for details.

Development

Contributions are welcome! Please open an issue or submit a pull request for suggestions or improvements.

This project uses uv to manage dependencies. Install uv:

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

Create a virtual environment and install dependencies:

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

Project Structure

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

Testing

Run tests with pytest:

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

# Run the tests
pytest

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

Tests cover:

Configuration validation
Server functionality
Error handling
Main application logic

Please add corresponding tests when adding new features.

Tools

Tool	Category	Description
`execute_query`	Query	Execute a KQL query against Azure Data Explorer
`list_tables`	Discovery	List all tables in the configured database
`get_table_schema`	Discovery	Get the schema for a specific table
`sample_table_data`	Discovery	Get sample data from a table with optional sample size

License

MIT