项目简介

ClickHouse MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，它允许大型语言模型 (LLM) 客户端通过 MCP 协议与 ClickHouse 数据库进行交互。该服务器将 ClickHouse 的数据库查询能力封装成易于 LLM 调用的工具，使得 LLM 能够安全、可控地访问和操作 ClickHouse 中的数据。

主要功能点

查询数据库列表: 获取 ClickHouse 服务器上所有数据库的名称。
查询数据表列表: 获取指定数据库中的所有数据表名称，并可选择根据名称模式进行过滤。同时提供数据表的结构信息。
执行 SQL 查询: 在 ClickHouse 数据库上执行 SELECT SQL 查询，并返回查询结果。所有查询均以只读模式执行，确保数据安全。

安装步骤

安装 'uv': 按照这里的说明安装 'uv'。
同步依赖: 在仓库根目录下运行 'uv sync' 安装项目依赖。然后运行 'source .venv/bin/activate' 激活虚拟环境。

配置环境变量: 创建 '.env.production' 文件，并根据你的 ClickHouse 数据库配置填写以下信息：

CLICKHOUSE_HOST=<你的ClickHouse主机地址>
CLICKHOUSE_PORT=<你的ClickHouse端口号>
CLICKHOUSE_USER=<你的ClickHouse用户名>
CLICKHOUSE_PASSWORD=<你的ClickHouse密码>

安装 MCP 服务器: 运行 'fastmcp install mcp_clickhouse/mcp_server.py -f .env.production' 命令安装服务器。
重启客户端: 重启你的 MCP 客户端（如 Claude Desktop）使服务器生效。

服务器配置

MCP 客户端需要配置以下 JSON 信息来连接 ClickHouse MCP 服务器：

{
  "server_name": "mcp-clickhouse",  // 服务器名称，与 mcp_server.py 中 MCP_SERVER_NAME 保持一致
  "command": "fastmcp",             // 启动服务器的命令，通常为 fastmcp
  "args": [                        // 启动命令的参数
    "run",                         // fastmcp 的 run 子命令，用于运行 MCP 服务器
    "mcp_clickhouse/mcp_server.py" // MCP 服务器的入口文件路径
  ]
}

基本使用方法

安装并配置服务器后，在支持 MCP 协议的 LLM 客户端中，你就可以使用以下工具与 ClickHouse 数据库进行交互了：

'list_databases()': 列出所有数据库。
'list_tables(database="<数据库名>")': 列出指定数据库中的所有表，例如 'list_tables(database="default")'。
'run_select_query(query="<SQL查询语句>")': 执行 SQL 查询，例如 'run_select_query(query="SELECT * FROM default.system.tables LIMIT 10")'。

请注意，所有数据库连接信息均通过环境变量配置，确保敏感信息安全。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息