Azure Data Explorer Mcp 伺服器

什麼是 ADX-MCP-Server？

ADX-MCP-Server 是一個模型上下文協議 (MCP) 伺服器，旨在幫助 AI 助手查詢和分析 Azure 數據探索 (ADX) 數據庫。它提供標準化的介面，簡化 AI 系統與數據庫之間的互動，使數據檢索和操作變得更加容易和有效。

ADX-MCP-Server 的特點

• 標準化介面：該伺服器提供一組標準化的 API，允許 AI 助手與 Azure 數據探索數據庫之間無縫通信。
• 數據查詢：用戶可以在 ADX 數據庫上執行複雜的查詢，實現高效的數據檢索和分析。
• AI 整合：該伺服器旨在支持 AI 應用程序，增強其處理和分析大型數據集的能力。
• 公共庫：ADX-MCP-Server 作為公共庫提供，允許開發者貢獻並增強其功能。
• MIT 許可證：該項目是開源的，並根據 MIT 許可證進行授權，促進開發者社區內的合作和共享。

如何使用 ADX-MCP-Server

1. 安裝：從 GitHub 克隆庫並按照文檔中提供的安裝說明進行操作。
2. 配置：通過配置必要的參數來設置伺服器，以連接到您的 Azure 數據探索實例。
3. API 訪問：利用標準化的 API 發送查詢並接收來自 ADX 數據庫的響應。
4. 整合：將伺服器與您的 AI 應用程序整合，以利用其查詢能力進行數據分析。

常見問題解答

Q1: ADX-MCP-Server 的目的是什么？

A1: ADX-MCP-Server 作為 AI 助手與 Azure 數據探索數據庫之間的橋樑，通過標準化介面實現高效的數據查詢和分析。

Q2: ADX-MCP-Server 是開源的嗎？

A2: 是的，ADX-MCP-Server 是一個開源項目，並在 GitHub 上根據 MIT 許可證提供。

Q3: 我可以為 ADX-MCP-Server 做貢獻嗎？

A3: 當然可以！歡迎貢獻。您可以分叉庫，進行更改並提交拉取請求。

Q4: 我該如何安裝 ADX-MCP-Server？

A4: 您可以通過從 GitHub 克隆庫並按照文檔中的安裝說明進行安裝。

Q5: 我可以使用 ADX-MCP-Server 執行什麼樣的查詢？

A5: 您可以運行各種查詢，包括複雜的分析查詢，以檢索和操作存儲在 Azure 數據探索數據庫中的數據。

Azure Data Explorer MCP Server

<a href="https://glama.ai/mcp/servers/1yysyd147h"> <img width="380" height="200" src="https://glama.ai/mcp/servers/1yysyd147h/badge" /> </a>

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.

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.)
  • Workload Identity credential support for AKS

• Docker containerization support

• Provide interactive tools for AI assistants

The 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.

Usage

1. Login to your Azure account which has the permission to the ADX cluster using Azure CLI.

2. 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

### Optional: Azure Workload Identity credentials 
### AZURE_TENANT_ID=your-tenant-id
### AZURE_CLIENT_ID=your-client-id 
### ADX_TOKEN_FILE_PATH=/var/run/secrets/azure/tokens/azure-identity-token

Azure Workload Identity Support

The 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.

For AKS with Azure Workload Identity, you only need to:

1. Make sure the pod has AZURE_TENANT_ID and AZURE_CLIENT_ID environment variables set
2. Ensure the token file is mounted at the default path or specify a custom path with ADX_TOKEN_FILE_PATH

If these environment variables are not present, the server will automatically fall back to DefaultAzureCredential, which tries multiple authentication methods in sequence.

3. 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 using:

docker build -t adx-mcp-server .

Running with Docker

You can run the server using Docker in several ways:

Using docker run directly:

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

Using docker-compose:

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

docker-compose up

Running with Docker in Claude Desktop

To use the containerized server with Claude Desktop, update the configuration to use Docker with the environment variables:

{
  "mcpServers": {
    "adx": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ADX_CLUSTER_URL",
        "-e", "ADX_DATABASE",
        "-e", "AZURE_TENANT_ID",
        "-e", "AZURE_CLIENT_ID",
        "-e", "ADX_TOKEN_FILE_PATH",
        "adx-mcp-server"
      ],
      "env": {
        "ADX_CLUSTER_URL": "https://yourcluster.region.kusto.windows.net",
        "ADX_DATABASE": "your_database",
        "AZURE_TENANT_ID": "your_tenant_id",
        "AZURE_CLIENT_ID": "your_client_id",
        "ADX_TOKEN_FILE_PATH": "/var/run/secrets/azure/tokens/azure-identity-token"
      }
    }
  }
}

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

Using as a Dev Container / GitHub Codespace

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

For more details, check the devcontainer README.

Development

Contributions are welcome! Please open an issue or submit a pull request if you have any suggestions or improvements.

This project uses uv to manage dependencies. Install uv following the instructions for your platform:

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

You can then create a virtual environment and install the dependencies with:

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

Project Structure

The project has been organized with a src directory 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

The project includes a comprehensive test suite that ensures functionality and helps prevent regressions.

Run the 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 are organized into:

• Configuration validation tests
• Server functionality tests
• Error handling tests
• Main application tests

When adding new features, please also add corresponding tests.

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