使用说明

项目简介

ClickHouse MCP Server 是一个基于 Model Context Protocol (MCP) 构建的后端服务，旨在为大型语言模型 (LLM) 应用提供与 ClickHouse 数据库交互的能力。它通过 MCP 协议将 ClickHouse 的数据查询、Schema 信息以及查询计划等功能以标准化的方式暴露给 LLM 客户端，使得 LLM 可以安全、可控地访问和利用 ClickHouse 数据库中的数据。

主要功能点

执行 ClickHouse 查询: 允许 LLM 客户端发送 SQL 查询到 ClickHouse 数据库并获取 JSON 格式的结果。
获取表 Schema: 提供获取 ClickHouse 表结构信息的功能，帮助 LLM 理解数据表的字段和类型。
解释查询计划: 支持查询语句的执行计划分析，使 LLM 能够理解查询的执行方式，辅助优化查询或理解性能瓶颈。
列出数据库表: 允许 LLM 客户端获取 ClickHouse 数据库中所有表的列表。

安装步骤

创建并激活虚拟环境 (推荐):

python -m venv venv
source venv/bin/activate  # 或 venv\Scripts\activate (Windows)

安装依赖:

pip install -r requirements.txt

安装 clickhouse-mcp:
```
pip install -e .
```

服务器配置

MCP 客户端需要配置以下 JSON 信息以连接到 ClickHouse MCP Server：

{
  "serverName": "clickhouse-mcp",
  "command": "python",
  "args": [
    "-m",
    "clickhouse_mcp.mcp_server"
  ]
}

配置参数注释:

'serverName': 服务器名称，可以自定义，例如 "clickhouse-mcp"。
'command': 启动服务器的命令，这里使用 'python'。
'args': 传递给 'python' 命令的参数，用于指定运行 'clickhouse_mcp.mcp_server' 模块来启动 MCP 服务器。

环境变量配置 (重要):

ClickHouse MCP Server 依赖以下环境变量来连接 ClickHouse 数据库，请确保在运行服务器之前配置好这些环境变量，例如在 '.env' 文件中配置（项目根目录下创建 '.env' 文件）：

CLICKHOUSE_HOST=your_clickhouse_host  # ClickHouse 主机地址
CLICKHOUSE_PORT=9000               # ClickHouse 端口，默认为 9000
CLICKHOUSE_USER=default            # ClickHouse 用户名
CLICKHOUSE_PASSWORD=your_password   # ClickHouse 密码 (如果设置了密码)

请将 'your_clickhouse_host' 和 'your_password' 替换为您的实际 ClickHouse 数据库连接信息。

基本使用方法

启动 MCP 服务器: 配置好环境变量后，在项目根目录下运行以下命令启动服务器：

python -m clickhouse_mcp.mcp_server

或者使用 'main.py' 入口：

python -m clickhouse_mcp

使用 MCP Inspector (可选): 可以使用 MCP Inspector 工具来检查服务器的功能和可用性。首先确保已安装 Inspector：

npm install -g @modelcontextprotocol/inspector

然后运行 Inspector 连接到 ClickHouse MCP Server：

npx @modelcontextprotocol/inspector python -m clickhouse_mcp

在 MCP 客户端中使用: 将上述 服务器配置 JSON 信息配置到您的 MCP 客户端中，客户端即可通过 MCP 协议调用 ClickHouse MCP Server 提供的工具，例如 'run_clickhouse_query', 'get_clickhouse_schema', 'explain_clickhouse_query', 'get_clickhouse_tables' 等，从而实现与 ClickHouse 数据库的交互。

关键词