Azure Kusto MCP Server

Azure Kusto MCP 服务

一个连接到 Azure Kusto 的模型上下文协议（MCP）服务，使 AI 助手能够探索数据架构并执行 KQL 查询。

功能

• Azure Kusto 集成：安全连接到 Azure Kusto 群集
• 架构探索：将表架构作为资源提供给 AI 助手
• 查询执行：提供运行 KQL 查询和分析结果的工具
• 数据分析辅助：内置常见数据分析任务的提示词
• VS Code 集成：在 VS Code 中以交互方式配置连接详情

要求

• Python 3.9+
• Azure Kusto 群集访问权限
• 带有 GitHub Copilot 或 Copilot Chat 扩展（支持 MCP）的 VS Code
• 所需的 Python 包（通过设置脚本自动安装）

快速设置（推荐）

使用 VS Code 集成设置 MCP 服务的最简单方式：

python setup-mcp.py

此脚本将：

1. 安装所有必需的依赖项
2. 创建 VS Code 集成所需的配置
3. 提供启动服务的说明

手动安装

1. 克隆此仓库：

git clone https://github.com/yourusername/kusto-mcp-server.git
cd kusto-mcp-server

2. 安装所需的依赖项：

pip install -r requirements.txt

3.（可选）配置环境变量： 在根目录中创建 .env 文件，并添加以下变量：

AZURE_KUSTO_CLUSTER=https://<your-cluster>.kusto.windows.net
AZURE_KUSTO_DATABASE=<your-database>

创建 mcp.json 配置文件

需要使用 mcp.json 文件为 VS Code 配置 MCP 服务。如果你选择手动设置，或设置脚本未创建此文件，请按照以下步骤操作：

1. 在工作区的 .vscode 目录中创建名为 mcp.json 的新文件（如果该目录不存在，请先创建）
2. 在文件中添加以下内容：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "kusto-cluster",
      "description": "Azure Kusto Cluster URL (e.g., https://mycluster.kusto.windows.net)",
      "default": ""
    },
    {
      "type": "promptString",
      "id": "kusto-database",
      "description": "Azure Kusto Database Name",
      "default": ""
    }
  ],
  "servers": {
    "Azure Kusto MCP": {
      "type": "stdio",
      "command": "${command:python.interpreterPath}",
      "args": ["${workspaceFolder}/src/kusto_mcp/server.py"],
      "env": {
        "AZURE_KUSTO_CLUSTER": "${input:kusto-cluster}",
        "AZURE_KUSTO_DATABASE": "${input:kusto-database}",
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  }
}

3. 如有需要，自定义配置：
   • 如果需要使用特定的 Python 解释器路径，请更改 command
   • 如果服务脚本位于其他位置，请修改 args
   • 如有需要，添加其他环境变量
   • 请注意，${workspaceFolder} 和 ${command:python.interpreterPath} 是 VS Code 变量，会自动替换为相应路径

此配置包含输入提示，每次启动服务时都会询问你的 Kusto 群集 URL 和数据库名称，方便你在不同数据库之间切换。

VS Code 集成

若要在 VS Code 中使用 MCP 服务：

1. 确保已运行设置脚本：python setup-mcp.py，或已手动创建 mcp.json 文件
2. 在 VS Code 中安装 GitHub Copilot 或 Copilot Chat 扩展
3. 打开命令面板（Ctrl+Shift+P）
4. 运行“MCP: Start Server with Configuration”
5. 从列表中选择“Azure Kusto MCP”
6. 按提示输入 Kusto 群集 URL 和数据库名称

MCP 服务将启动并连接到你的 Copilot Chat 会话，让你能够：

• 使用 connect 工具连接到 Kusto 群集
• 浏览表架构
• 执行查询
• 分析数据

不使用 VS Code 运行服务

直接启动 MCP 服务：

python -m src.kusto_mcp.server

如果尚未在 .env 文件中配置连接信息，服务会在需要时提示你输入连接详情。

身份验证

此服务使用 Azure 的 DefaultAzureCredential 进行身份验证，支持以下方式：

1. 环境变量
2. 托管标识
3. Azure CLI 凭据
4. Azure PowerShell 凭据
5. 作为后备选项的交互式浏览器身份验证

连接前，请确保至少通过上述一种方式完成身份验证。

资源类型

此服务提供以下资源：

• kusto/tables - 当前数据库中所有表的列表
• kusto/schema/{table_name} - 特定表的架构
• kusto/sample - KQL 查询示例及说明
• kusto/connection - 当前连接信息

工具

以下工具可供使用：

• connect - 连接到 Kusto 群集和数据库
• connection_status - 检查当前连接状态
• execute_query - 运行 KQL 查询
• analyze_data - 执行查询并分析结果
• optimize_query - 获取查询优化建议

工具使用指南

Kusto MCP 服务提供了多种工具，用于与 Azure Kusto 交互。以下介绍如何有效使用每种工具：

Connect 工具

connect 工具用于建立与 Azure Kusto 群集和数据库的连接。

在 Copilot Chat 中使用：

I need to connect to my Kusto cluster

此工具会提示你输入：

• 群集 URL（例如 https://yourcluster.kusto.windows.net）
• 数据库名称

身份验证会通过 Azure 的 DefaultAzureCredential 自动处理。

示例：

Connect to the Kusto database named "MyDatabase" on the cluster "analytics.kusto.windows.net"

Connection Status 工具

connection_status 工具会显示当前连接的详细信息。

在 Copilot Chat 中使用：

Check my current Kusto connection

输出示例：

✅ Connected to Azure Kusto.
        
- **Cluster**: https://analytics.kusto.windows.net
- **Database**: MyDatabase

Execute Query 工具

execute_query 工具会针对已连接的数据库运行 KQL 查询。

在 Copilot Chat 中使用：

Run this KQL query: <your query here>

示例：

Run this KQL query: StormEvents | where State == "FLORIDA" | take 10

对于较大的结果集（>100 行），该工具会返回摘要和前 10 行。

Analyze Data 工具

analyze_data 工具会执行查询并分析结果。

在 Copilot Chat 中使用：

Analyze this query: <your query here>

你可以指定分析类型：

• summary（默认）：数据的基本统计信息
• stats：详细的统计分析，包括相关性
• plot_ready：帮助可视化数据的信息

示例：

Analyze this query with stats analysis: StormEvents | summarize count() by State | top 10 by count_

Optimize Query 工具

optimize_query 工具会提供改进 KQL 查询的建议。

在 Copilot Chat 中使用：

Optimize this KQL query: <your query here>

示例：

Optimize this KQL query: 
StormEvents
| project *
| where StartTime > ago(7d)
| sort by StartTime desc

高级使用场景

探索表架构

探索可用表及其架构：

What tables are available in this database?

检查特定表的架构：

Show me the schema for the StormEvents table

时间序列分析

进行基于时间的数据分析：

Help me analyze time trends in the StormEvents table using the StartTime column

相关性分析

查找列之间的关系：

Find correlations between DamageProperty and DeathsDirect in the StormEvents table

数据质量检查

验证数据质量：

Check for null values and outliers in the StormEvents table

逐步构建查询

对于复杂查询，你可以请求指导：

I need to build a query that shows storm events by state, with damage amounts, limited to the top 10 most expensive events. Can you help me construct this?

最佳实践

1. 始终先连接：运行查询前，先使用 connect 工具
2. 验证连接：不确定连接状态时，使用 connection_status 工具
3. 从小型查询开始：在大型数据集上运行查询前，使用 take 或 limit 运算符进行测试
4. 使用分析工具：analyze_data 工具只需少量操作即可提供有价值的见解
5. 请求优化建议：对于运行时间较长或复杂的查询，使用 optimize_query 工具

KQL 查询示例

以下是一些 KQL 查询示例，可帮助你开始使用：

// Simple filtering
StormEvents 
| where State == "FLORIDA" 
| take 10

// Aggregation
StormEvents
| summarize EventCount=count() by State
| order by EventCount desc
| take 10

// Time filtering
StormEvents
| where StartTime > ago(30d)
| summarize EventCount=count() by bin(StartTime, 1d)
| render timechart

// Join example
StormEvents
| where EventType == "Tornado"
| join (
    StormEvents 
    | where EventType == "Flood"
    | project State, FloodTime=StartTime
) on State
| project State, TornadoTime=StartTime, FloodTime
| take 10

MCP 配置故障排除

如果 MCP 配置遇到问题：

1. 缺少 mcp.json：按照上述说明，在 .vscode 目录中手动创建该文件
2. 未显示配置：确保 mcp.json 文件格式正确，并位于 .vscode 目录中
3. 服务无法连接：检查 mcp.json 文件中指定的主机名和端口是否可用
4. Copilot 未检测到服务：创建或修改 mcp.json 文件后，重启 VS Code

常见问题故障排除

除了前面提到的一般故障排除建议外，以下是常见工具问题的具体解决方案：

Connect 工具问题

• 错误：“Failed to connect”：确认 Azure 凭据有效，并且你有权访问指定的群集和数据库
• 超时错误：检查网络连接和防火墙设置
• 身份验证失败：确保已通过 az login 登录 Azure，或已设置有效的环境凭据

查询执行问题

• 大型查询超时：添加筛选条件或时间限制，以减少数据量
• 语法错误：使用 optimize_query 工具检查并修复查询语法
• 缺少列：查询前通过架构探索确认列名

数据分析问题

• 分析结果为空：分析前确保查询返回了数据
• 相关性错误：检查数据是否至少包含两列数值列，以进行相关性分析
• 可视化准备：对于 plot_ready 分析，同时包含类别列和数值列，以获得最佳结果

与 AI 助手搭配使用

此 MCP 服务旨在与支持 Model Context Protocol 的 AI 助手配合使用。该服务提供对 Azure Kusto 数据的结构化访问，使 AI 助手能够：

1. 浏览可用的表和架构
2. 执行只读 KQL 查询
3. 分析查询结果
4. 提供数据分析指导

安全注意事项

• 此服务使用 Azure 的 DefaultAzureCredential 进行安全身份验证
• 只有具备适当权限的用户才能访问 Kusto 集群
• 服务本身不会存储凭据

许可证

MIT 许可证