使用说明

项目简介

该项目 'mcp-server-kusto' 是一个基于 Model Context Protocol (MCP) 的服务器端实现，旨在为LLM应用提供访问 Azure Data Explorer (ADX / Kusto) 数据库的能力。通过该MCP服务器，LLM客户端可以利用预定义的工具，安全、便捷地查询和检索ADX数据库中的数据信息。

主要功能点

列出数据表和视图: 支持列出ADX数据库中的内部表、外部表和物化视图。
执行Kusto查询: 允许执行Kusto查询语言 (KQL) 查询，以检索内部表、外部表或物化视图中的数据。
获取表结构: 提供获取内部表和外部表结构信息的功能。

所有功能均通过预定义的工具暴露给MCP客户端，客户端可以通过调用这些工具与ADX数据库进行交互。

安装步骤

克隆仓库

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

安装依赖 确保您已安装 'uv' (或者 'pip') 包管理器。推荐使用 'uv' 以获得更快的安装速度。

# 使用 uv (推荐)
uv pip install -r requirements.txt

# 或者使用 pip
pip install -r requirements.txt

服务器配置

要将此MCP服务器配置到支持MCP协议的LLM客户端（例如 Claude Desktop），您需要提供服务器的启动命令和参数。以下是配置示例，请根据您的实际环境进行调整。

配置信息 (JSON 格式):

{
  "mcpServers": {
    "kusto": {
      "command": "uv",
      "args": [
        "--directory",
        "{{PATH_TO_PROJECT}}\\mcp-server-kusto\\src\\mcp_server_kusto",
        "run",
        "mcp-server-kusto",
        "--cluster",
        "{{ADX_CLUSTER_URL}}",
        "--authority_id",
        "{{TENANT_ID}}",
        "--client_id",
        "{{CLIENT_ID}}",
        "--client_secret",
        "{{CLIENT_SECRET}}"
      ]
    }
  }
}

参数注释:

'"kusto"': MCP服务器的名称，您可以自定义，用于在客户端中标识该服务器。
'"command": "uv"': 启动服务器的命令，这里假设您使用 'uv' 运行 Python 脚本。如果使用 'pip'，您可能需要使用 'python' 或 'python3'。
'"args"': 传递给启动命令的参数列表。
- '"--directory", "{{PATH_TO_PROJECT}}\mcp-server-kusto\src\mcp_server_kusto"': 指定项目 'src/mcp_server_kusto' 目录为工作目录，'{{PATH_TO_PROJECT}}' 需要替换为您的项目实际路径。
- '"run"': 使用 'uv run' 运行 Python 模块。
- '"mcp-server-kusto"': 指定要运行的 Python 模块名称，对应 'src/mcp_server_kusto/init.py' 中定义的 'main' 函数。
- '"--cluster", "{{ADX_CLUSTER_URL}}"': 必需参数，您的 Azure Data Explorer 集群 URL，例如 'https://your_cluster.kusto.windows.net'。 '{{ADX_CLUSTER_URL}}' 需要替换为您的实际集群 URL。
- '"--authority_id", "{{TENANT_ID}}"': 可选参数 (取决于ADX集群的认证方式)，Azure 租户 ID，用于服务主体认证。如果您的ADX集群使用服务主体认证，则需要提供。 '{{TENANT_ID}}' 需要替换为您的实际租户 ID。
- '"--client_id", "{{CLIENT_ID}}"': 可选参数 (取决于ADX集群的认证方式)，Azure 服务主体客户端 ID。如果您的ADX集群使用服务主体认证，则需要提供。 '{{CLIENT_ID}}' 需要替换为您的实际客户端 ID。
- '"--client_secret", "{{CLIENT_SECRET}}"': 可选参数 (取决于ADX集群的认证方式)，Azure 服务主体客户端密钥。如果您的ADX集群使用服务主体认证，则需要提供。 '{{CLIENT_SECRET}}' 需要替换为您的实际客户端密钥。

本地 ADX 模拟器配置:

如果您使用本地 Azure Data Explorer 模拟器，可以简化配置，无需提供认证信息。集群 URL 类似于 'http://localhost:8082'。

{
  "mcpServers": {
    "kusto": {
      "command": "uv",
      "args": [
        "--directory",
        "{{PATH_TO_PROJECT}}\\mcp-server-kusto\\src\\mcp_server_kusto",
        "run",
        "mcp-server-kusto",
        "--cluster",
        "{{ADX_CLUSTER_URL}}"
      ]
    }
  }
}

基本使用方法

启动MCP服务器: 配置完成后，启动您的LLM客户端，客户端会自动启动 'mcp-server-kusto' MCP服务器。
使用工具: 在LLM应用中，您可以指示LLM使用以下工具来与ADX数据库交互:
- 'list_internal_tables': 列出内部表。需要提供 'database' 参数 (数据库名称)。
- 'list_external_tables': 列出外部表。需要提供 'database' 参数 (数据库名称)。
- 'list_materialized_views': 列出物化视图。需要提供 'database' 参数 (数据库名称)。
- 'execute_query_internal_table': 执行内部表或物化视图查询。需要提供 'database' (数据库名称) 和 'query' (KQL查询语句) 参数。
- 'execute_query_external_table': 执行外部表查询。需要提供 'database' (数据库名称) 和 'query' (KQL查询语句) 参数。
- 'retrieve_internal_table_schema': 获取内部表或物化视图结构。需要提供 'database' (数据库名称) 和 'table' (表名或视图名) 参数。
- 'retrieve_external_table_schema': 获取外部表结构。需要提供 'database' (数据库名称) 和 'table' (表名) 参数。

LLM客户端会根据您的指令和工具的定义，自动调用相应的工具并返回结果。

示例对话:

用户: "列出数据库 'mydatabase' 中的所有表" LLM (可能调用工具): 'list_internal_tables(database="mydatabase")' MCP服务器 (返回结果): '["table1", "table2", "view1"]' LLM (回复用户): "数据库 'mydatabase' 中包含表: table1, table2 和视图: view1"

用户: "查询 'mytable' 表的前10行数据" LLM (可能调用工具): 'execute_query_internal_table(database="mydatabase", query="mytable | limit 10")' MCP服务器 (返回结果): '[{"column1": "value1", "column2": "value2"}, ...]' LLM (回复用户): "查询结果如下: ... (展示表格数据)"

请注意，实际使用方式取决于您的LLM客户端的具体实现。

关键词