AI导哈

Kusto MCP服务器

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

  • by ashishroy077
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 ashishroy077/mcp-kusto

使用说明

Azure Kusto MCP服务器

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

特性

  • Azure Kusto集成：安全连接到Azure Kusto群集
  • 模式探索：将表模式作为AI助手的资源公开
  • 查询执行：用于运行KQL查询和分析结果的工具
  • 数据分析辅助：常见数据分析任务的内置提示
  • VS代码集成：在VS Code中交互式配置连接详细信息

需求

  • Python 3.9+
  • Azure Kusto群集访问
  • 带有GitHub Copilot或Copilot Chat扩展的VS代码（用于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
  1. 安装所需的依赖项：
pip install -r requirements.txt
  1. （可选）配置环境变量： 创建一个 .env 根目录中的文件，包含以下变量：
AZURE_KUSTO_CLUSTER=https://<your-cluster>.kusto.windows.net
AZURE_KUSTO_DATABASE=<your-database>

创建mcp.json配置文件

这 mcp.json 使用VS代码配置MCP服务器需要文件。如果您是手动设置的，或者安装脚本没有创建此文件，请按照以下步骤操作：

  1. 创建一个名为的新文件 mcp.json 在 .vscode 工作区的目录（如果不存在，请创建此目录）
  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}"
      }
    }
  }
}
  1. 如果需要，自定义配置：
    • 更改 command 如果你需要使用特定的Python解释器路径
    • 修改 args 如果您的服务器脚本位于其他位置
    • 如果需要，添加其他环境变量
    • 请注意 ${workspaceFolder} 和 ${command:python.interpreterPath} 是将自动替换为适当路径的VS代码变量

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

VS代码集成

要使用带有VS代码的MCP服务器：

  1. 确保您已运行安装脚本： python setup-mcp.py 或手动创建 mcp.json 文件
  2. 在VS代码中安装GitHub Copilot或Copilot Chat扩展
  3. 打开命令面板（Ctrl+Shift+P）
  4. 运行“MCP：使用配置启动服务器”
  5. 从列表中选择“Azure Kusto MCP”
  6. 出现提示时，输入Kusto集群URL和数据库名称

MCP服务器将启动并连接到您的Copilot聊天会话，允许您：

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

不使用VS代码运行服务器

直接使用以下命令启动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 该工具建立与Azure Kusto集群和数据库的连接。

在Copilot聊天中的用法：

I need to connect to my Kusto cluster

此工具将提示您：

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

身份验证是通过Azure的DefaultAzureCredentials自动处理的。

例子：

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

连接状态工具

这 connection_status 该工具显示您当前的连接详细信息。

在Copilot聊天中的用法：

Check my current Kusto connection

输出示例：

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

执行查询工具

这 execute_query 该工具对连接的数据库运行KQL查询。

在Copilot聊天中的用法：

Run this KQL query: <your query here>

例子：

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

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

分析数据工具

这 analyze_data 该工具执行查询并对结果进行分析。

在Copilot聊天中的用法：

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 该工具提供了改进KQL查询的建议。

在Copilot聊天中的用法：

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. 使用分析工具：The 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. 副驾驶未检测到服务器：创建或修改后重新启动VS代码 mcp.json 文件

常见问题排查

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

连接工具问题

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

查询执行问题

  • 大型查询超时：添加过滤器或时间限制以减少数据量
  • 语法错误：使用 optimize_query 用于检查和修复查询语法的工具
  • 缺少列：查询前使用架构探索验证列名

数据分析问题

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

使用AI助手

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

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

安全考虑

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

许可证

MIT许可证

相关 MCP