mcp-clickhouse

🚀 ClickHouse MCP 服务器

ClickHouse MCP 服务器提供了一系列工具，可在 ClickHouse 集群上执行 SQL 查询、列出数据库和表等操作。同时，文档详细介绍了配置和开发流程，帮助用户快速搭建和使用该服务器。

✨ 主要特性

工具

• run_select_query
  • 此工具用于在你的 ClickHouse 集群上执行 SQL 查询。
  • 输入参数为 sql（字符串类型），即要执行的 SQL 查询内容。
  • 所有 ClickHouse 查询都会以 readonly = 1 模式运行，以此确保查询操作的安全性。
• list_databases
  • 该工具可列出你的 ClickHouse 集群上的所有数据库。
• list_tables
  • 用于在指定数据库中列出所有表。
  • 输入参数为 database（字符串类型），即数据库名称。

📦 安装指南

⚠️ 重要提示

这是一个临时的配置流程，一旦包发布将会得到显著改进。

1. 运行 uv sync 来安装依赖项。若要安装 uv，请按照 此处 的说明进行操作。安装完成后，执行 source .venv/bin/activate 激活虚拟环境。
2. 使用 ClickHouse 凭据设置 .env.production 文件，示例如下：

CLICKHOUSE_HOST=<CLICKHOUSE_HOST>
CLICKHOUSE_PORT=<CLICKHOUSE_PORT>
CLICKHOUSE_USER=<CLICKHOUSE_USER>
CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

3. 运行 fastmcp install mcp_clickhouse/mcp_server.py -f .env.production 来安装服务器。
4. 重启 Claude Desktop 使配置生效。

🔧 开发步骤

1. 在 test-services 目录下运行 docker compose up -d 以启动 ClickHouse 集群。
2. 将以下变量添加到根目录的 .env 文件中：

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

3. 运行 uv sync 来安装依赖项。若要安装 uv，请按照 此处 的说明进行操作。安装完成后，执行 source .venv/bin/activate 激活虚拟环境。
4. 为了方便测试，可以运行 fastmcp dev mcp_clickhouse/mcp_server.py 来启动 MCP 服务器。