ClickHouse MCP Server
Overview
基本能力
产品定位
mcp-clickhouse 是一个专为 ClickHouse 数据库设计的 MCP 服务器，旨在提供便捷的数据库查询和管理功能。
核心功能
- 执行 SQL 查询：通过
run_select_query工具执行 SQL 查询，所有查询均以只读模式运行以确保安全。 - 列出数据库：通过
list_databases工具列出 ClickHouse 集群中的所有数据库。 - 列出表：通过
list_tables工具列出指定数据库中的所有表。
适用场景
- 数据分析：执行复杂的 SQL 查询以分析数据。
- 数据库管理：快速查看和管理数据库和表结构。
- 开发测试：在开发环境中测试和验证 SQL 查询。
工具列表
- run_select_query
- 功能：在 ClickHouse 集群上执行 SQL 查询。
-
输入：
sql（字符串）：要执行的 SQL 查询。 -
list_databases
-
功能：列出 ClickHouse 集群中的所有数据库。
-
list_tables
- 功能：列出指定数据库中的所有表。
- 输入：
database（字符串）：数据库名称。
常见问题解答
- 如何配置 ClickHouse 连接？
-
通过环境变量配置
CLICKHOUSE_HOST、CLICKHOUSE_USER、CLICKHOUSE_PASSWORD等参数。 -
如何启用 HTTPS 连接？
-
设置
CLICKHOUSE_SECURE=true并确保CLICKHOUSE_PORT为8443。 -
如何禁用 SSL 证书验证？
- 设置
CLICKHOUSE_VERIFY=false（不推荐用于生产环境）。
使用教程
使用依赖
-
安装
uv工具：bash pip install uv -
确保 Python 3.13 已安装。
安装教程
- 在 Claude Desktop 配置文件中添加以下内容（路径因操作系统而异）：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%/Claude/claude_desktop_config.json
json
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.13",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "<clickhouse-host>",
"CLICKHOUSE_PORT": "<clickhouse-port>",
"CLICKHOUSE_USER": "<clickhouse-user>",
"CLICKHOUSE_PASSWORD": "<clickhouse-password>",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true",
"CLICKHOUSE_CONNECT_TIMEOUT": "30",
"CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
}
}
}
}
-
替换
uv的绝对路径（可通过which uv查找）。 -
重启 Claude Desktop 以应用更改。
调试方式
-
在
test-services目录下运行以下命令启动 ClickHouse 集群：bash docker compose up -d -
在项目根目录创建
.env文件并添加以下内容：env CLICKHOUSE_HOST=localhost CLICKHOUSE_PORT=8123 CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=clickhouse -
安装依赖并激活虚拟环境：
bash uv sync source .venv/bin/activate -
启动 MCP 服务器：
bash mcp dev mcp_clickhouse/mcp_server.py