使用说明

项目简介

ClickHouse数据助手是一个基于Model Context Protocol (MCP) 的服务器实现，专门为AI助手设计，使其能够安全、结构化地探索和分析ClickHouse数据库。通过此服务器，AI助手可以列出数据库中的表，读取表数据，并执行SQL查询，从而实现对数据库的智能交互和数据分析。

主要功能点

资源浏览：允许AI助手获取ClickHouse数据库中的表列表，并查看表的结构和描述信息。
数据读取：支持AI助手读取指定表的数据，以便理解数据内容。
SQL执行：提供安全可控的SQL查询执行能力，AI助手可以发送SQL查询语句，并获取查询结果。
权限控制：通过只读查询限制，保障数据库安全，防止恶意操作。
易于集成：遵循MCP协议标准，可以方便地与任何兼容MCP协议的AI客户端集成。

安装步骤

安装 Python 和 uv 包管理器

确保你的系统已安装 Python 环境，并使用 'uv' 包管理器安装项目依赖。如果尚未安装 'uv'，请参考 uv installation guide。
安装 ClickHouse

确保已安装并运行 ClickHouse 数据库。如果尚未安装，请参考 ClickHouse 官方文档进行安装。

克隆仓库

将 'clickhouse_mcp_server' 仓库克隆到本地：

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

安装 Python 依赖

在项目根目录下，使用 'uv' 安装 Python 依赖：
```
uv pip install -r requirements.txt
```
(仓库中没有 requirements.txt 文件，但根据 'README.md' 提示，可能存在依赖，如果运行报错，需要手动安装 'clickhouse-connect' 和 'mcp-server' 等依赖)

配置环境变量或命令行参数

根据 'README.md' 的指引，配置 ClickHouse 数据库连接信息。

方法一：环境变量 (推荐) 设置以下环境变量，替换为你的 ClickHouse 数据库连接信息：

export CLICKHOUSE_HOST=你的ClickHouse主机地址
export CLICKHOUSE_PORT=你的ClickHouse端口号
export CLICKHOUSE_USER=你的ClickHouse用户名
export CLICKHOUSE_PASSWORD=你的ClickHouse密码
export CLICKHOUSE_DATABASE=你的ClickHouse数据库名

方法二：命令行参数 在启动服务器时，可以通过命令行参数指定数据库连接信息。

服务器配置

为了让 MCP 客户端（例如 Cline）连接到 ClickHouse MCP 服务器，你需要配置客户端的 'mcpServers' 字段。以下是一个配置示例，你需要根据你的实际环境进行调整：

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/clickhouse_mcp_server",  // 替换为 clickhouse_mcp_server 仓库的绝对路径
        "run",
        "-m",
        "clickhouse_mcp_server.server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "你的ClickHouse主机地址",    // 替换为你的 ClickHouse 主机地址，如果使用环境变量方式配置，则此处可以省略
        "CLICKHOUSE_PORT": "你的ClickHouse端口号",     // 替换为你的 ClickHouse 端口号，如果使用环境变量方式配置，则此处可以省略
        "CLICKHOUSE_USER": "你的ClickHouse用户名",     // 替换为你的 ClickHouse 用户名，如果使用环境变量方式配置，则此处可以省略
        "CLICKHOUSE_PASSWORD": "你的ClickHouse密码",   // 替换为你的 ClickHouse 密码，如果使用环境变量方式配置，则此处可以省略
        "CLICKHOUSE_DATABASE": "你的ClickHouse数据库名"  // 替换为你的 ClickHouse 数据库名，如果使用环境变量方式配置，则此处可以省略
      }
    }
  }
}

配置参数说明:

'"clickhouse"': MCP 服务器的名称，可以自定义，用于在客户端中标识该服务器连接。
'"command": "uv"': 启动服务器的命令，这里使用 'uv' 包管理器来运行 Python 模块。
'"args"': 传递给 'uv run' 命令的参数列表。
- '"--directory", "/path/to/clickhouse_mcp_server"': 指定 'uv' 命令的工作目录为 'clickhouse_mcp_server' 仓库的绝对路径。请务必替换为实际路径。
- '"run", "-m", "clickhouse_mcp_server.server"': 使用 'uv run -m' 命令执行 'clickhouse_mcp_server.server' 模块，启动 MCP 服务器。
'"env"': 设置环境变量，用于传递 ClickHouse 数据库连接信息。如果已经设置了全局环境变量，这里可以省略，否则请根据实际情况配置。

基本使用方法

启动 MCP 服务器

在 'clickhouse_mcp_server' 仓库根目录下，打开终端并执行以下命令启动服务器：

uv run -m clickhouse_mcp_server.server

或者，如果使用命令行参数配置数据库连接，可以这样启动：

uv run -m clickhouse_mcp_server.server --host 你的ClickHouse主机地址 --port 你的ClickHouse端口号 --user 你的ClickHouse用户名 --password 你的ClickHouse密码 --database 你的ClickHouse数据库名

服务器成功启动后，将监听 MCP 客户端的请求。

在 MCP 客户端中使用

在兼容 MCP 协议的客户端（例如 Cline）中，按照上述 服务器配置 部分的说明配置 'mcpServers'。配置完成后，客户端即可连接到 ClickHouse MCP 服务器。

与 AI 助手交互

在客户端中，你可以向 AI 助手提出关于 ClickHouse 数据库的问题，例如：

What tables are in the database?
Show me the data in the 'sales_data' table.
What is the sales volume in each region?
Which product is the best-selling?

AI 助手将通过 MCP 服务器访问 ClickHouse 数据库，并返回查询结果。

注意: 请根据你的实际 ClickHouse 环境和 'clickhouse_mcp_server' 仓库的路径，正确配置环境变量、命令行参数和客户端配置信息。

关键词