Azure Data Explorer MCP 服务器

一个用于 Microsoft Fabric 中的 Azure Data Explorer/Eventhouse 的 模型上下文协议（MCP） 服务器。

它通过标准化的 MCP 接口提供对 Azure Data Explorer/Eventhouse 集群和数据库的访问，使 AI 助手能够执行 KQL 查询并探索您的数据。

功能

• 对 Azure Data Explorer 执行 KQL 查询

• 发现和探索数据库资源

  • 列出配置数据库中的表
  • 查看表架构
  • 从表中采样数据
  • 获取表统计信息/详情

• 身份验证支持

  • 令牌凭证支持（Azure CLI、MSI 等）
  • 用于 AKS 的工作负载身份凭证支持

• Docker 容器化支持

• 为 AI 助手提供交互式工具

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

使用方法

1. 使用 Azure CLI 登录到具有对 ADX 集群权限的 Azure 账户。

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

# 必需：Azure Data Explorer 配置
ADX_CLUSTER_URL=https://yourcluster.region.kusto.windows.net
ADX_DATABASE=your_database

# 可选：Azure 工作负载身份凭证 
# 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 工作负载身份支持

服务器在运行于具有工作负载身份配置的 Azure Kubernetes Service (AKS) 环境时默认使用 WorkloadIdentityCredential。当必要的环境变量存在时，它优先使用 WorkloadIdentityCredential。

对于使用 Azure 工作负载身份的 AKS，您只需要：

1. 确保 Pod 设置了 AZURE_TENANT_ID 和 AZURE_CLIENT_ID 环境变量
2. 确保令牌文件位于默认路径或使用 ADX_TOKEN_FILE_PATH 指定自定义路径

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

3. 将服务器配置添加到您的客户端配置文件中。例如，对于 Claude Desktop：

{
  "mcpServers": {
    "adx": {
      "command": "uv",
      "args": [
        "--directory",
        "<adx-mcp-server 完整路径>",
        "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 对象中提供实际值。

作为 Dev Container / GitHub Codespace 使用

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

有关更多详细信息，请查看 devcontainer README。

开发

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

此项目使用 uv 来管理依赖项。按照您的平台的说明安装 uv：

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

然后，您可以创建虚拟环境并使用以下命令安装依赖项：

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

项目结构

项目已使用 src 目录结构组织：

adx-mcp-server/
├── src/
│   └── adx_mcp_server/
│       ├── __init__.py      # 包初始化
│       ├── server.py        # MCP 服务器实现
│       └── main.py          # 主应用程序逻辑
├── Dockerfile               # Docker 配置
├── docker-compose.yml       # Docker Compose 配置
├── .dockerignore            # Docker 忽略文件
├── pyproject.toml           # 项目配置
└── README.md                # 此文件

测试

该项目包含一个全面的测试套件，确保功能并帮助防止回归。

使用 pytest 运行测试：

# 安装开发依赖
uv pip install -e ".[dev]"

# 运行测试
pytest

# 运行带覆盖率报告的测试
pytest --cov=src --cov-report=term-missing

测试按以下类别组织：

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

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

工具

许可证

MIT