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 扩展的 VS Code（用于 MCP 支持）
• 必需的 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 群集 URL（例如，https://mycluster.kusto.windows.net）",
      "default": ""
    },
    {
      "type": "promptString",
      "id": "kusto-database",
      "description": "Azure Kusto 数据库名称",
      "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 集成

要将 MCP 服务器与 VS Code 一起使用：

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 工具问题

• 错误：“连接失败”：验证您的 Azure 凭据是否有效，并且您有权访问指定的群集和数据库
• 超时错误：检查您的网络连接和防火墙设置
• 身份验证失败：确保您已使用 az login 登录到 Azure 或具有有效的环境凭据

查询执行问题

• 大型查询超时：添加过滤器或时间约束以减少数据量
• 语法错误：使用 optimize_query 工具检查并修复您的查询语法
• 缺少列：在查询之前使用模式探索验证列名

数据分析问题

• 空分析结果：确保您的查询在分析之前返回数据
• 相关性错误：检查您的数据是否包含至少两列用于相关性分析的数字列
• 可视化准备：对于 plot_ready 分析，包括分类列和数字列以获得最佳结果

与 AI 助手一起使用

此 MCP 服务器旨在与支持模型上下文协议的 AI 助手一起使用。 该服务器提供对 Azure Kusto 数据的结构化访问，允许 AI 助手：

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

安全注意事项

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

许可证

MIT 许可证