Unleash the Power of Azure Data Explorer with the Model Context Protocol (MCP)

This repository provides a robust and streamlined MCP server specifically designed for Azure Data Explorer (ADX). By leveraging the Model Context Protocol, this server empowers Large Language Models (LLMs) with direct access to your ADX data, enabling sophisticated AI-driven insights and automation. Imagine your AI assistant seamlessly querying your data, understanding its structure, and providing actionable intelligence – all within a standardized and secure framework.

Key Capabilities

KQL Query Execution: Execute complex Kusto Query Language (KQL) queries against your ADX cluster with ease.
Dynamic Data Discovery:
- Table Listing: Effortlessly enumerate all tables within your designated database.
- Schema Retrieval: Obtain detailed schema information for any table, allowing the LLM to understand data structure.
- Data Sampling: Extract representative data samples from tables to provide context and grounding for LLM reasoning.
Robust Authentication: Securely connect to your ADX cluster using token-based authentication, supporting Azure CLI, Managed Service Identity (MSI), and other credential providers.
Containerized Deployment: Deploy the server effortlessly using Docker, ensuring consistent and isolated execution across environments.
Interactive AI Tooling: Expose a suite of powerful tools to AI assistants, enabling them to interact with your data in a meaningful way. The toolset is fully configurable, allowing you to tailor the available functionality to your specific needs and context window limitations.

Getting Started

Prerequisites

An Azure account with access to an Azure Data Explorer cluster.
Azure CLI installed and configured with appropriate permissions to access the ADX cluster.

Configuration

Authentication: Ensure you are logged into your Azure account with the necessary permissions to access your ADX cluster. This is typically done via the Azure CLI:
```
az login
```

Environment Variables: Configure the following environment variables, either in a .env file or directly in your system environment:

ADX_CLUSTER_URL=https://yourcluster.region.kusto.windows.net  # Your ADX cluster URL
ADX_DATABASE=your_database                                    # The database to connect to

Client Integration: Integrate the server configuration into your LLM client. Here's an example configuration 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 encounter an Error: spawn uv ENOENT in Claude Desktop, ensure that the full path to uv is correctly specified or set the environment variable NO_UV=1 in the configuration.

Docker Deployment

Simplify deployment and ensure consistency with Docker.

Building the Image

docker build -t adx-mcp-server .

Running the Container

Direct Execution:

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

Docker Compose: Create a .env file with your ADX credentials and execute:
```
docker-compose up
```

Claude Desktop Integration with Docker

To leverage the containerized server within Claude Desktop, modify the configuration as follows:

{
  "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"
      }
    }
  }
}

This configuration seamlessly passes environment variables from Claude Desktop to the Docker container.

Development and Contribution

We welcome contributions! Feel free to open issues or submit pull requests with suggestions and improvements.

This project utilizes uv for dependency management.

Install uv: Follow the installation instructions for your operating system.
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Create 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 Overview

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

A comprehensive test suite is included to ensure functionality and prevent regressions.

Install Development Dependencies:
```
uv pip install -e ".[dev]"
```
Run Tests:
```
pytest
```

Run with Coverage Report:

pytest --cov=src --cov-report=term-missing

The test suite covers:

Configuration validation
Server functionality
Error handling
Main application logic

When introducing new features, please include corresponding tests.

Available Tools

Tool	Category	Description
`execute_query`	Query	Executes a KQL query against Azure Data Explorer.
`list_tables`	Discovery	Lists all tables in the configured database.
`get_table_schema`	Discovery	Retrieves the schema for a specific table.
`sample_table_data`	Discovery	Retrieves sample data from a table with an optional sample size parameter.