ClickHouse MCP Server 使用说明

项目简介

ClickHouse MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，它将 ClickHouse 数据库的功能通过 MCP 协议暴露出来，使得大型语言模型 (LLM) 等 MCP 客户端能够以标准化的方式访问 ClickHouse 数据库的元数据和执行查询操作。

主要功能点

资源浏览: 允许 LLM 客户端浏览 ClickHouse 服务器上的数据库和表，并将它们作为资源进行管理。
模式发现: 支持获取 ClickHouse 表的结构信息（Schema），方便 LLM 理解数据表内容。
数据查询: 提供工具 (Tool) 让 LLM 客户端能够执行 SELECT 查询，从 ClickHouse 数据库中检索数据。

安装步骤

克隆仓库

git clone https://github.com/ThomAub/clickhouse_mcp_server.git
cd clickhouse_mcp_server

安装依赖

uv sync --all-extras

或者如果你的环境中没有 'uv'，可以使用 'pip' （但推荐使用 'uv'）：

pip install -r requirements.txt

配置 ClickHouse 连接信息 你需要配置连接 ClickHouse 数据库的信息。可以通过以下两种方式配置：
- 环境变量: 设置以下环境变量：
  - 'CLICKHOUSE_HOST': ClickHouse 服务器地址 (默认为 'localhost')
  - 'CLICKHOUSE_PORT': ClickHouse 服务器端口 (默认为 '8123')
  - 'CLICKHOUSE_USER': ClickHouse 用户名 (默认为 'default')
  - 'CLICKHOUSE_PASSWORD': ClickHouse 密码 (默认为空)
  - 'CLICKHOUSE_DATABASE': 默认数据库名 (默认为 'default')
- 修改代码: 直接修改 'clickhouse_mcp_server/server.py' 文件中的 'get_clickhouse_client' 函数，将连接信息硬编码在函数中（不推荐）。

服务器配置

以下 JSON 配置信息可以用于 MCP 客户端连接到 ClickHouse MCP Server。你需要将这段配置添加到你的 MCP 客户端的服务器配置中。

{
  "serverName": "ClickHouse MCP Server",  // MCP 服务器的名称，可以自定义
  "command": "python",                     // 启动 MCP 服务器的命令，这里使用 python
  "args": ["clickhouse_mcp_server/server.py"], // 启动命令的参数，指定服务器脚本路径
  "transports": ["stdio"]                  // 使用 stdio (标准输入输出) 作为通信协议
}

基本使用方法

确保 ClickHouse 服务器已启动并可访问。

按照安装步骤配置并启动 ClickHouse MCP Server：

python clickhouse_mcp_server/server.py

在你的 MCP 客户端中，配置上述服务器配置信息，并连接到 ClickHouse MCP Server。
客户端连接成功后，可以：
- 列出资源 (Resources): 浏览 ClickHouse 数据库和表。
- 读取资源 (Read Resource): 获取数据库中表的结构信息。
- 调用工具 (Call Tool): 使用 'execute_select_query' 工具执行 SELECT 查询，检索 ClickHouse 数据。

关键词