🚀 MCP KQL Server

MCP KQL 服务

mcp-name: io.github.4R9UN/mcp-kql-server

AI 驱动的 KQL 查询执行：支持自然语言到 KQL（NL2KQL）的转换与执行

一个 Model Context Protocol（MCP）服务，可将自然语言问题转换为经过优化的 KQL 查询，并提供智能架构发现、AI 驱动的缓存以及与 Azure Data Explorer 的无缝集成。只需用通俗英语提问，即可即时获得准确的 KQL 查询和上下文感知结果。

最新版本：v2.1.5 - 符合策略的 Azure CLI 登录方式，并迁移至官方 MCP Python SDK。

🎬 演示

观看 MCP KQL Server 的快速演示：

🚀 功能

• execute_kql_query：

  • 自然语言转 KQL：根据自然语言描述生成 KQL 查询。
  • 直接执行 KQL：执行原始 KQL 查询。
  • 多种输出格式：支持 JSON、CSV 和表格格式。
  • 严格架构验证：使用已发现的架构记忆，并在执行前进行验证。
  • 基于架构的修复：仅当有效的表架构能够证明替换项正确时，才修复无效列。

• kql_schema_memory：

  • 架构发现：发现并缓存表的架构。
  • 数据库探索：列出数据库中的所有表。
  • AI 上下文：获取按相关性排序的表 CAG 上下文，并可选择输出限定于表范围的严格架构。
  • 分析报告：生成带有可视化内容的报告。
  • 缓存管理：清除或刷新架构缓存。
  • 记忆统计信息：获取记忆使用情况的统计数据。

📊 MCP 工具执行流程

graph TD
    A[👤 User Submits KQL Query] --> B{🔍 Query Validation}
    B -->|❌ Invalid| C[📝 Syntax Error Response]
    B -->|✅ Valid| D[🧠 Load Schema Context]

    D --> E{💾 Schema Cache Available?}
    E -->|✅ Yes| F[⚡ Load from Memory]
    E -->|❌ No| G[🔍 Discover Schema]

    F --> H[🎯 Execute Query]
    G --> I[💾 Cache Schema + AI Context]
    I --> H

    H --> J{🎯 Query Success?}
    J -->|❌ Error| K[🚨 Enhanced Error Message]
    J -->|✅ Success| L[📊 Process Results]

    L --> M[🎨 Generate Visualization]
    M --> N[📤 Return Results + Context]

    K --> O[💡 AI Suggestions]
    O --> N

    style A fill:#4a90e2,stroke:#2c5282,stroke-width:2px,color:#ffffff
    style B fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
    style C fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ffffff
    style D fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
    style E fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
    style F fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
    style G fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style H fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff
    style I fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style J fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
    style K fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ffffff
    style L fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
    style M fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
    style N fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
    style O fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff

架构记忆发现流程

架构记忆流程已集成到查询执行中，但现在会在尝试实时发现之前复用现有的缓存架构。如果 CAG／架构记忆中已存在表架构，服务将使用该缓存架构，而不是重新为其编制索引。

graph TD
    A[👤 User Requests Schema Discovery] --> B[🔗 Connect to Cluster]
    B --> C[📂 Enumerate Databases]
    C --> D[📋 Discover Tables]

    D --> E[🔍 Get Table Schemas]
    E --> F[🤖 AI Analysis]
    F --> G[📝 Generate Descriptions]

    G --> H[💾 Store in Memory]
    H --> I[📊 Update Statistics]
    I --> J[✅ Return Summary]

    style A fill:#4a90e2,stroke:#2c5282,stroke-width:2px,color:#ffffff
    style B fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
    style C fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style D fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff
    style E fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
    style F fill:#e67e22,stroke:#bf6516,stroke-width:2px,color:#ffffff
    style G fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
    style H fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style I fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff
    style J fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff

📋 前置条件

• Python 3.10 或更高版本
• 已安装 Azure CLI。服务启动时会检查当前令牌，并仅在需要时运行普通的交互式 az login。
• 有权访问 Azure Data Explorer 集群

🚀 一条命令安装

快速安装（推荐）

从源代码安装

git clone https://github.com/4R9UN/mcp-kql-server.git && cd mcp-kql-server && pip install -e .

其他安装方式

pip install mcp-kql-server

就是这么简单！ 服务会自动：

• ✅ 在 %APPDATA%\KQL_MCP（Windows）或 ~/.local/share/KQL_MCP（Linux/Mac）中设置内存目录
• ✅ 配置适用于生产环境的最佳默认值
• ✅ 抑制冗长的 Azure SDK 日志
• ✅ 无需设置环境变量

📱 MCP 客户端配置

一次性安装（适用于所有平台）：

pip install --upgrade mcp-kql-server

安装后，将 MCP 客户端配置为通过 Python 模块入口点启动服务：python -m mcp_kql_server。只要 Python 位于 PATH 中，此方式就适用于所有平台，且不依赖 mcp-kql-server 控制台脚本的位置。（pip 仍会安装该控制台脚本，并继续支持它以保持向后兼容——请参阅下面的替代配置片段。）

Claude Desktop

将以下内容添加到 Claude Desktop MCP 设置文件（mcp_settings.json）中：

位置：

• Windows：%APPDATA%\Claude\mcp_settings.json
• macOS：~/Library/Application Support/Claude/mcp_settings.json
• Linux：~/.config/Claude/mcp_settings.json

{
  "mcpServers": {
    "mcpKqlServer": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "mcp_kql_server"]
    }
  }
}

{
  "mcpServers": {
    "mcpKqlServer": {
      "type": "stdio",
      "command": "py",
      "args": ["-3", "-m", "mcp_kql_server"]
    }
  }
}

VSCode（搭配 MCP 扩展）

将以下内容添加到 VSCode MCP 配置中：

Settings.json 位置：

• Windows：%APPDATA%\Code\User\mcp.json
• macOS：~/Library/Application Support/Code/User/mcp.json
• Linux：~/.config/Code/User/mcp.json

{
  "servers": {
    "mcpKqlServer": {
      "type": "stdio",
      "command": "py",
      "args": ["-3", "-m", "mcp_kql_server", "--transport", "stdio"],
      "timeout": 300000,
      "env": {
        "FASTMCP_TRANSPORT": "stdio",
        "MCP_KQL_AUTH_ON_STARTUP": "true",
        "MCP_KQL_CHECK_FOR_UPDATES": "false",
        "MCP_KQL_SKIP_STARTUP_VERSION_CHECK": "1",
        "MCP_KQL_AUTH_CHECK_TIMEOUT_SECONDS": "10",
        "MCP_KQL_AUTH_LOGIN_TIMEOUT_SECONDS": "120",
        "MCP_KQL_SQLITE_BUSY_TIMEOUT_MS": "30000"
      }
    }
  }
}

如果 VS Code 日志显示 spawn ...PythonNNN/python.exe ENOENT，说明 Python 扩展正在将 "python" 替换为缓存的解释器路径。请改用 "py"（Windows）/ "python3"（macOS/Linux），或改用 pip install 添加到 PATH 的 "mcp-kql-server" 控制台脚本。详情请参阅 docs/troubleshooting.md。

Windows 提示：使用 py -3 -m mcp_kql_server，这样 VS Code 就不需要特定于用户的 Python 路径。如果必须在本地使用完整路径，请将其保存在私人 mcp.json 中，而不要放入共享文档。

如果服务已启动，但 VS Code 仍未显示工具，请运行 MCP: Reset Cached Tools，然后运行 MCP: Reset Trust，并从 MCP: List Servers 重启服务。VS Code 会将信任状态和缓存的工具分别存储在 mcp.json 之外，因此先前启动失败可能会导致旧的空状态一直保留，直到重置为止。

多个 MCP 客户端共享 HTTP 模式

当 VS Code、GitHub Copilot CLI、Agent 或其他 MCP 客户端需要连接到同一个持久运行的 MCP KQL 服务进程时，请使用共享 HTTP。

默认情况下，HTTP 仅绑定到环回地址，因为工具调用会使用操作员的 Azure CLI 身份执行。在向远程开放前，请先在受信任的反向代理中配置身份验证和 TLS。非环回绑定必须显式确认 MCP_KQL_ALLOW_UNAUTHENTICATED_REMOTE_HTTP=true。

启动服务：

python -m mcp_kql_server --transport http --host 127.0.0.1 --port 8000 --http-path /mcp --stateless-http

客户端配置：

{
  "servers": {
    "mcpKqlServer": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

运行时设置

嵌入模型采用延迟加载。更改模型后，刷新时会重新嵌入架构；其他模型生成的向量会被忽略，而不会混合使用。

Roo-code 或 Cline（VS-code 扩展）

在 Roo-code 或 Cline 的 MCP 设置中提问或添加：

MCP 设置位置：

• 所有平台：通过 Roo-code 扩展设置或 mcp_settings.json

{
  "mcp-kql-server": {
    "type": "stdio",
    "command": "python",
    "args": ["-m", "mcp_kql_server"],
    "alwaysAllow": []
  }
}

通用 MCP 客户端

适用于任何兼容 MCP 的应用程序：

# Preferred: invoke as a Python module (cross-platform)
python -m mcp_kql_server

# Platform-stable launchers (recommended if `python` is ambiguous on PATH)
py -3 -m mcp_kql_server     # Windows
python3 -m mcp_kql_server   # macOS / Linux

# Equivalent console script installed by pip
mcp-kql-server

# Shared HTTP mode for multiple clients
python -m mcp_kql_server --transport http --host 127.0.0.1 --port 8000 --http-path /mcp --stateless-http

# Server provides these tools:
# - execute_kql_query: Execute KQL or generate KQL from natural language
# - kql_schema_memory: Discover, cache, and inspect cluster schemas

🔧 快速入门

1. 启动 MCP 服务（零配置）

python -m mcp_kql_server

服务启动时会在后台开始检查 Azure CLI 令牌，并且仅在需要时运行普通的交互式 az login。Kusto 工具调用不会启动登录；执行前会等待启动任务完成。若要在启动服务前手动进行身份验证，请运行：

az login

若要查看已安装的服务版本和运行时默认值：

python -m mcp_kql_server --info --json

服务会立即启动，并具备以下特性：

• 📁 自动创建内存路径：%APPDATA%\KQL_MCP\cluster_memory
• 🔧 优化的默认设置：无需配置文件
• 🔐 安全配置：使用现有的 Azure CLI 凭据
• ⚡ 快速响应启动：MCP 发现会立即开始，同时在后台初始化身份验证

3. 通过 MCP 客户端使用

服务提供两个主要工具：

execute_kql_query - 执行 KQL 查询，或根据自然语言生成 KQL

kql_schema_memory - 发现、刷新和检查缓存的集群架构

💡 使用示例

基本查询执行

向 MCP 客户端（如 Claude）提出请求：

“针对 help 集群执行此 KQL 查询：cluster('help.kusto.windows.net').database('Samples').StormEvents | take 10，总结结果并提供一些高层次的见解。”

复杂分析查询

向 MCP 客户端提出请求：

“查询 help 集群中的 Samples 数据库，显示风暴事件数量排名前 10 的州，并包含可视化内容。”

架构发现

向 MCP 客户端提问：

“发现并缓存 help.kusto.windows.net 集群的架构，然后告诉我有哪些数据库和表”

带上下文的数据探索

向 MCP 客户端提问：

“使用 help 集群 Samples 数据库中的 StormEvents 表，显示 2007 年所有损失估算超过 100 万美元的龙卷风事件”

基于时间的分析

向 MCP 客户端提问：

“分析 StormEvents 表中 2007 年按月划分的风暴事件，按事件类型分组并以可视化形式展示”

🎯 主要优势

面向数据分析师

• ⚡ 加快查询开发：AI 驱动的自动补全和建议
• 🎨 丰富的可视化效果：即时生成 Markdown 表格，便于探索数据
• 🧠 上下文感知：无需文档即可了解数据结构

面向 DevOps 团队

• 🔄 自动发现架构：保持架构信息最新
• 💾 智能缓存：减少 API 调用并提升性能
• 🔐 安全身份验证：利用现有 Azure CLI 凭据

面向 AI 应用

• 🤖 智能查询辅助：AI 生成的表说明和建议
• 📊 结构化数据访问：为下游处理提供整洁、类型明确的响应
• 🎯 上下文感知响应：丰富的元数据，助力 AI 做出更好的决策

🏗️ 架构

%%{init: {'theme':'dark', 'themeVariables': {
  'primaryColor':'#1a1a2e',
  'primaryTextColor':'#00d9ff',
  'primaryBorderColor':'#00d9ff',
  'secondaryColor':'#16213e',
  'secondaryTextColor':'#c77dff',
  'secondaryBorderColor':'#c77dff',
  'tertiaryColor':'#0f3460',
  'tertiaryTextColor':'#ffaa00',
  'tertiaryBorderColor':'#ffaa00',
  'lineColor':'#00d9ff',
  'textColor':'#ffffff',
  'mainBkg':'#0a0e27',
  'nodeBorder':'#00d9ff',
  'clusterBkg':'#16213e',
  'clusterBorder':'#9d4edd',
  'titleColor':'#00ffff',
  'edgeLabelBackground':'#1a1a2e',
  'fontFamily':'Inter, Segoe UI, sans-serif',
  'fontSize':'16px',
  'flowchart':{'nodeSpacing':60, 'rankSpacing':80, 'curve':'basis', 'padding':20}
}}}%%
graph LR
    Client["🖥️ MCP Client<br/><b>Claude / AI / Custom</b><br/>─────────<br/>Natural Language<br/>Interface"]

    subgraph Server["🚀 MCP KQL Server"]
        direction TB
        FastMCP["⚡ FastMCP<br/>Framework<br/>─────────<br/>MCP Protocol<br/>Handler"]
        NL2KQL["🧠 NL2KQL<br/>Engine<br/>─────────<br/>AI Query<br/>Generation"]
        Executor["⚙️ Query<br/>Executor<br/>─────────<br/>Validation &<br/>Execution"]
        Memory["💾 Schema<br/>Memory<br/>─────────<br/>AI Cache"]

        FastMCP --> NL2KQL
        NL2KQL --> Executor
        Executor --> Memory
        Memory --> Executor
    end

    subgraph Azure["☁️ Azure Services"]
        direction TB
        ADX["📊 Azure Data<br/>Explorer<br/>─────────<br/><b>Kusto Cluster</b><br/>KQL Engine"]
        Auth["🔐 Azure<br/>Identity<br/>─────────<br/>Interactive<br/>CLI Auth"]
    end

    %% Client to Server
    Client ==>|"📡 MCP Protocol<br/>stdio or streamable HTTP"| FastMCP

    %% Server to Azure
    Executor ==>|"🔍 Execute KQL<br/>Query & Analyze"| ADX
    Executor -->|"🔐 Authenticate"| Auth
    Memory -.->|"📥 Fetch Schema<br/>On Demand"| ADX

    %% Styling - Using cyberpunk palette
    style Client fill:#1a1a2e,stroke:#00d9ff,stroke-width:4px,color:#00ffff
    style FastMCP fill:#16213e,stroke:#c77dff,stroke-width:3px,color:#c77dff
    style NL2KQL fill:#1a1a40,stroke:#ffaa00,stroke-width:3px,color:#ffaa00
    style Executor fill:#16213e,stroke:#9d4edd,stroke-width:3px,color:#9d4edd
    style Memory fill:#0f3460,stroke:#00d9ff,stroke-width:3px,color:#00d9ff
    style ADX fill:#1a1a2e,stroke:#ff6600,stroke-width:4px,color:#ff6600
    style Auth fill:#16213e,stroke:#00ffff,stroke-width:2px,color:#00ffff

    style Server fill:#0a0e27,stroke:#9d4edd,stroke-width:3px,stroke-dasharray: 5 5
    style Azure fill:#0a0e27,stroke:#ff6600,stroke-width:3px,stroke-dasharray: 5 5

由 MCP-KQL-Server 生成的报告 | ⭐ 在 GitHub 上为此仓库点星

🚀 生产环境部署

准备好将 MCP KQL Server 部署到 Azure 以供生产使用了吗？我们为 Azure Container Apps 提供全面的部署自动化，具备企业级安全性和可扩展性。

🌟 功能

• ✅ 无服务器计算：支持自动缩放的 Azure Container Apps
• ✅ 托管标识：通过 Azure AD 实现无密码身份验证
• ✅ 基础设施即代码：使用 Bicep 模板实现可复现的部署
• ✅ 监控：集成 Log Analytics 和 Application Insights
• ✅ 默认安全：网络隔离、RBAC 和最低权限访问
• ✅ 一键部署：自动化 PowerShell 和 Bash 脚本

📖 部署指南

有关完整的部署说明、架构详情和故障排除信息：

👉 查看生产环境部署指南

指南包含：

• 🏗️ 详细的架构图
• ⚙️ 分步部署说明（PowerShell 和 Bash）
• 🔒 安全配置最佳实践
• 🐛 常见问题故障排除
• 📦 Docker 容器化详情

快速部署

# PowerShell (Windows)
cd deployment
.\deploy.ps1 -SubscriptionId "YOUR_SUB_ID" -ResourceGroupName "mcp-kql-prod-rg" -ClusterUrl "https://yourcluster.region.kusto.windows.net"

# Bash (Linux/Mac/WSL)
cd deployment
./deploy.sh --subscription "YOUR_SUB_ID" --resource-group "mcp-kql-prod-rg" --cluster-url "https://yourcluster.region.kusto.windows.net"

📁 项目结构

mcp-kql-server/
├── mcp_kql_server/
│   ├── __init__.py          # Package initialization
│   ├── mcp_server.py        # Main MCP server implementation
│   ├── execute_kql.py       # KQL query execution logic
│   ├── memory.py            # Advanced memory management
│   ├── kql_auth.py          # Azure authentication
│   ├── utils.py             # Utility functions
│   └── constants.py         # Configuration constants
├── docs/                    # Documentation
├── Example/                 # Usage examples
├── pyproject.toml          # Project configuration
└── README.md               # This file

🔒 安全

• Azure CLI 身份验证：重用现有令牌，或启动交互式浏览器登录
• 不存储凭据：服务不会存储身份验证令牌
• 本地内存：架构缓存存储在本地，不会传输

🐛 故障排除

常见问题

1. 身份验证错误

   # Re-authenticate with Azure CLI
   az login --tenant your-tenant-id
   

2. 内存问题

   # The memory cache is now managed automatically. If you suspect issues,
   # you can clear the cache directory, and it will be rebuilt on the next query.
   # Windows:
   rmdir /s /q "%APPDATA%\KQL_MCP\unified_memory.json"
   
   # macOS/Linux:
   rm -rf ~/.local/share/KQL_MCP/cluster_memory
   

3. 连接超时

   • 检查集群 URI 格式
   • 验证网络连接
   • 确认 Azure 权限

🤝 贡献

欢迎贡献！请开始贡献。

📞 支持

• 问题：GitHub Issues
• PyPI 软件包：PyPI 项目页面
• 作者：Arjun Trivedi
• 认证：MCPHub

🌟 星标历史

mcp-name: io.github.4R9UN/mcp-kql-server

祝查询愉快！🎉