使用说明

Azure数据资源管理器MCP服务器

A. 模型上下文协议（MCP）服务器，使AI助手能够执行KQL查询，并通过标准化接口探索Azure Data Explorer（ADX/Kusto）数据库。

此服务器提供对Azure Data Explorer和Eventhouse（在Microsoft Fabric中）集群的无缝访问，允许AI助手使用强大的Kusto查询语言查询和分析您的数据。

特性

查询执行

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

数据库发现

列出表格 -发现数据库中的所有表
查看架构 -检查表架构和列类型
样本数据 -使用可配置的样本大小预览表格内容
表统计 -获取详细的元数据，包括行数和存储大小

认证

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

部署选项

多个传输 -stdio（默认）、HTTP和服务器发送事件（SSE）
Docker支持 -具有安全最佳实践的生产就绪容器映像
Dev容器 -GitHub Codespace无缝开发体验

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

用法

使用Azure CLI登录到具有ADX群集权限的Azure帐户。
通过以下方式为ADX集群配置环境变量 .env 文件或系统环境变量：

# 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）环境中运行时，服务器默认使用WorkloadIdentityCredentials。只要存在必要的环境变量，它就会优先使用WorkloadIdentityCredential。

对于具有Azure工作负载标识的AKS，您只需要：

确保吊舱有 AZURE_TENANT_ID 和 AZURE_CLIENT_ID 环境变量集
确保令牌文件已装载到默认路径，或指定一个自定义路径 ADX_TOKEN_FILE_PATH

如果这些环境变量不存在，服务器将自动回退到DefaultAzureCredential，它将按顺序尝试多种身份验证方法。

将服务器配置添加到客户端配置文件中。例如，对于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"
      }
    }
  }
}

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

Docker使用

该项目包括Docker支持，便于部署和隔离。

构建Docker镜像

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

docker build -t adx-mcp-server .

使用Docker运行

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

直接使用docker运行：

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编写：

创建一个 .env 使用Azure数据资源管理器凭据创建文件，然后运行：

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

此配置通过使用以下命令将环境变量从Claude Desktop传递到Docker容器 -e 仅使用变量名标记，并在 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代码空间

此存储库也可以用作无缝开发体验的开发容器。开发容器设置位于 devcontainer-feature/adx-mcp-server 文件夹。

有关更多详细信息，请查看 devcontainer自述文件.

发展

欢迎投稿！如果您有任何建议或改进，请打开问题或提交拉取请求。

此项目使用 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数据资源管理器执行KQL查询	`query` （string）-要执行的KQL查询
`list_tables`	发现	列出已配置数据库中的所有表	无
`get_table_schema`	发现	获取特定表的架构	`table_name` （string）-表的名称
`sample_table_data`	发现	从表中获取示例数据	`table_name` （字符串）， `sample_size` （int，默认值：10）
`get_table_details`	发现	获取表统计信息和元数据	`table_name` （string）-表的名称

配置

所需的环境变量

变量	描述	示例
`ADX_CLUSTER_URL`	Azure数据资源管理器群集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`

许可证

麻省理工学院