Azure Data Explorer MCP Server

Azure Data Explorer MCP 服务

一个 Model Context Protocol（MCP）服务，通过标准化接口让 AI 助手能够执行 KQL 查询并浏览 Azure Data Explorer（ADX/Kusto）数据库。

此服务可无缝访问 Azure Data Explorer 和 Eventhouse（位于 Microsoft Fabric 中）集群，让 AI 助手能够使用强大的 Kusto Query Language 查询和分析数据。

功能

查询执行

• 执行 KQL 查询 - 对 ADX 数据库执行任意 KQL 查询
• 结构化结果 - 获取格式为 JSON 的结果，便于使用

数据库发现

• 列出表 - 查找数据库中的所有表
• 查看架构 - 检查表架构和列类型
• 样本数据 - 以可配置的样本数量预览表内容
• 表统计信息 - 获取详细元数据，包括行数和存储大小

身份验证

• DefaultAzureCredential - 支持 Azure CLI、托管标识等
• 工作负载标识 - 原生支持 AKS 工作负载标识
• 灵活的凭据 - 支持多种 Azure 身份验证方式

部署选项

• 多种传输方式 - stdio（默认）、HTTP 和 Server-Sent Events（SSE）
• Docker 支持 - 采用安全最佳实践的生产就绪容器映像
• Dev Container - 借助 GitHub Codespaces 实现无缝开发体验

工具列表可配置，因此你可以选择要向 MCP 客户端提供哪些工具。如果你不使用某些功能，或者不想占用过多上下文窗口，这会很有用。

用法

1. 使用 Azure CLI 登录有权访问 ADX 集群的 Azure 帐户。

2. 通过 .env 文件或系统环境变量配置 ADX 集群的环境变量：

# 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

# Optional: Custom MCP Server configuration
ADX_MCP_SERVER_TRANSPORT=stdio # Choose between http/sse/stdio, default = stdio

# Optional: Only relevant for non-stdio transports
ADX_MCP_BIND_HOST=127.0.0.1 # default = 127.0.0.1
ADX_MCP_BIND_PORT=8080 # default = 8080

Azure 工作负载标识支持

在已配置工作负载标识的 Azure Kubernetes Service（AKS）环境中运行时，此服务现在默认使用 WorkloadIdentityCredential。只要存在必要的环境变量，它就会优先使用 WorkloadIdentityCredential。

对于使用 Azure Workload Identity 的 AKS，你只需：

1. 确保 Pod 已设置 AZURE_TENANT_ID 和 AZURE_CLIENT_ID 环境变量
2. 确保令牌文件已挂载到默认路径，或使用 ADX_TOKEN_FILE_PATH 指定自定义路径

如果不存在这些环境变量，服务会自动回退到 DefaultAzureCredential，后者会依次尝试多种身份验证方式。

3. 将服务配置添加到客户端配置文件中。以 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"
      }
    }
  }
}

注意：如果你在 Claude Desktop 中看到 Error: spawn uv ENOENT，可能需要指定 uv 的完整路径，或在配置中设置环境变量 NO_UV=1。

Docker 用法

此项目支持 Docker，便于部署和隔离。

构建 Docker 映像

使用以下命令构建 Docker 映像：

docker build -t adx-mcp-server .

使用 Docker 运行

你可以通过多种方式使用 Docker 运行此服务：

直接使用 docker run：

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

使用 docker-compose：

创建包含 Azure Data Explorer 凭据的 .env 文件，然后运行：

docker-compose up

在 Claude Desktop 中使用 Docker 运行

要在 Claude Desktop 中使用容器化的服务，请更新配置，使用 Docker 和环境变量：

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

此配置通过使用 -e 标志并仅提供变量名，将 Claude Desktop 中的环境变量传递给 Docker 容器；实际值则在 env 对象中提供。

使用 Docker 和 HTTP 传输

对于 HTTP 模式部署，可以使用以下 Docker 配置：

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

用作开发容器 / GitHub Codespace

此仓库也可用作开发容器，提供流畅的开发体验。开发容器设置位于 devcontainer-feature/adx-mcp-server 文件夹中。

如需了解详情，请查看 开发容器 README。

开发

欢迎贡献！如果你有任何建议或改进，请提交 issue 或 pull request。

此项目使用 uv 管理依赖项。请按照适用于你平台的说明安装 uv：

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 .

项目结构

此项目采用 src 目录结构：

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

测试

此项目包含全面的测试套件，用于确保功能正常并帮助防止回归问题。

使用 pytest 运行测试：

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

# Run the tests
pytest

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

测试分为以下几类：

• 配置验证测试
• 服务功能测试
• 错误处理测试
• 主应用程序测试

添加新功能时，也请添加相应的测试。

可用工具

工具	类别	描述	参数
execute_query	查询	对 Azure Data Explorer 执行 KQL 查询	query（字符串）- 要执行的 KQL 查询
list_tables	发现	列出已配置数据库中的所有表	无
get_table_schema	发现	获取特定表的架构	table_name（字符串）- 表名
sample_table_data	发现	获取表中的示例数据	table_name（字符串），sample_size（整数，默认值：10）
get_table_details	发现	获取表的统计信息和元数据	table_name（字符串）- 表名

配置

必需的环境变量

变量	描述	示例
ADX_CLUSTER_URL	Azure Data Explorer 集群 URL	https://yourcluster.region.kusto.windows.net
ADX_DATABASE	要连接的数据库名称	your_database

可选的环境变量

Azure 工作负载标识（适用于 AKS）

变量	描述	默认值
AZURE_TENANT_ID	Azure AD 租户 ID	-
AZURE_CLIENT_ID	Azure AD 客户端/应用程序 ID	-
ADX_TOKEN_FILE_PATH	工作负载标识令牌文件的路径	/var/run/secrets/azure/tokens/azure-identity-token

MCP 服务配置

变量	描述	默认值
ADX_MCP_SERVER_TRANSPORT	传输模式：stdio、http 或 sse	stdio
ADX_MCP_BIND_HOST	要绑定的主机（仅限 HTTP/SSE）	127.0.0.1
ADX_MCP_BIND_PORT	端口（仅限 HTTP/SSE）	8080

日志记录

变量	描述	默认值
LOG_LEVEL	日志级别：DEBUG、INFO、WARNING、ERROR	INFO

许可证

MIT

---