← 返回目录

MCP ClickHouse

官方

将 ClickHouse 连接到您的 AI 助手

查看安装方法 ↓ 横向对比 GitHub 源仓库 ↗

分类: 数据库第 1 / 58
Stars: ★ 883 非常热门
传输方式: stdio（本地进程）
运行环境: Python 3.10+ · Docker
凭据: 可选 API Key
许可证: Apache-2.0
最近提交: 4 天前
工具数: 4

79FMRS · B

官方 MCP 服务器，功能完善，但需注意权限配置和安全性。

最强项 · 安全与权限 18/20 最弱项 · 可靠性 12/20

可靠性

12/20

安全与权限

18/20

维护活跃度

17/20

文档质量

17/20

安装易用性

15/20

查看各项评分依据

可靠性 12/20: 证据：仓库是官方 ClickHouse 项目，包含测试目录（tests/test_tool.py、tests/test_chdb_tool.py）、Ruff 检查、Docker Compose 测试服务以及详尽的配置变量文档，服务器基于 FastMCP 构建，工具声明与 README 一致（run_query、list_databases、list_tables、run_chdb_select_query）。受静态审查限制，未实际执行任何代码，因此依据规则将可靠性上限设为 12。扣分原因：无法验证实际握手和工具行为，且依赖外部数据库配置；文档提到 MCP Inspector 和测试命令，但静态证据不足以证明完整运行链路。
安全与权限 18/20: 证据：默认强制 read-only（CLICKHOUSE_ALLOW_WRITE_ACCESS=false），破坏性操作（DROP/TRUNCATE）需要额外的 CLICKHOUSE_ALLOW_DROP=true 双重确认；HTTP/SSE 传输默认要求认证（静态令牌或 OAuth/OIDC），未认证则启动失败；/health 端点刻意不认证且响应体最小化以防泄露；密码标记为 isSecret；文档明确警告避免使用默认或管理员数据库用户，并建议最小权限。未发现红旗问题（无恶意行为、无真实令牌示例、无默认破坏性操作）。扣分原因：静态审查无法验证凭证在运行时是否被充分保护（如日志脱敏），且 read-only 检查的实现细节需要执行测试才能完全确认。
维护活跃度 17/20: 证据：Apache-2.0 许可证；仓库包含版本号（0.4.0）、PyPI/OCI 包、活跃的 CI（Ruff、pytest、Docker Compose）、明确的开发与测试流程。Stars 和问题数仅作为发现信号，未计入得分。扣分原因：静态证据无法确认发布频率、问题响应时效或依赖更新节奏；未见独立的安全响应渠道（如 security.md）在给定材料中明确展示。
文档质量 17/20: 证据：文档分层清晰：快速开始、完整环境变量表、认证三种模式、安全默认值、常见配置陷阱、示例配置（本机 Docker、ClickHouse Cloud、SQL Playground、chDB）、错误排查提示（如端口误用）以及健康检查说明。工具参数、分页、超时、权限开关均有文档。扣分原因：文档未提供独立的故障排查章节（如常见错误码和诊断步骤），部分配置（如中间件）需要用户自行推断 Python 环境细节，静态证据无法验证文档与真实行为的完全一致。
安装易用性 15/20: 证据：提供多种安装路径：PyPI（uv run 或 pip/系统 Python）、OCI 镜像、stdio/http/sse 传输；给出 Claude Desktop 配置 JSON 示例、SQL Playground 试玩示例、chDB 可选安装以及环境变量默认值。这些证据使设置路径清晰。扣分原因：静态审查无法执行安装步骤；依赖 uv 等外部工具且未在源代码中验证其启动行为；按校准规则，无执行证据时 setup 最高为 15。

静态评测 · 未实际运行收录于 2026-08-07

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络连接数据库

适合谁

已经使用 ClickHouse 并希望通过 MCP 让 AI 助手直接访问数据的团队。
需要快速、只读的数据查询和数据库探索场景。

不适合谁

需要数据库写入权限且未显式开启写访问的场景。
对安全性要求极高，不希望使用默认权限配置的生产环境。

所需权限

需要 ClickHouse 数据库的只读访问权限（默认）。
可选：通过 CLICKHOUSE_ALLOW_WRITE_ACCESS 启用写入权限。
可选：通过 CLICKHOUSE_ALLOW_DROP 启用破坏性操作权限。

风险与副作用

如果启用写入权限，AI 可能执行意外修改。
如果启用 DROP 权限，可能误删数据。
凭据可能通过环境变量暴露。

安装接入

准备工作

运行环境：Python 3.10+ · Docker

CLICKHOUSE_HOST 必填 ClickHouse 服务器的主机名（数据库端点，非 MCP 监听地址），由你的 ClickHouse 服务或 ClickHouse Cloud 提供。

CLICKHOUSE_USER 必填 ClickHouse 登录用户名，由数据库管理员分配；避免使用默认或管理员账号。

CLICKHOUSE_PASSWORD 必填密钥 ClickHouse 登录密码，由数据库管理员分配；请保密。

CLICKHOUSE_MCP_AUTH_TOKEN 可选密钥 HTTP/SSE 传输用的静态 Bearer 令牌，可用 uuidgen 或 openssl rand -hex 32 自行生成。

其他可选配置项（21 个）

CLICKHOUSE_PORT 可选 ClickHouse HTTP 接口端口，默认 8443（HTTPS）/ 8123（HTTP），通常无需设置。

CLICKHOUSE_SECURE 可选是否对 ClickHouse 数据库连接使用 HTTPS，默认 true。

CLICKHOUSE_VERIFY 可选是否验证 ClickHouse 连接的 SSL 证书，默认 true。

CLICKHOUSE_CONNECT_TIMEOUT 可选 ClickHouse 客户端连接超时秒数，默认 30。

CLICKHOUSE_SEND_RECEIVE_TIMEOUT 可选 ClickHouse 客户端收发超时秒数，默认 300，长查询可调大。

CLICKHOUSE_DATABASE 可选可选的默认数据库名，使用你自己的 ClickHouse 中的库名。

CLICKHOUSE_ROLE 可选可选的会话激活 ClickHouse 角色，由数据库管理员分配。

CLICKHOUSE_ALLOW_WRITE_ACCESS 可选设为 true 允许 DDL/DML 写操作，默认只读。

CLICKHOUSE_ALLOW_DROP 可选设为 true 且同时开启写访问时，允许 DROP/TRUNCATE 等破坏性操作。

CLICKHOUSE_MCP_QUERY_TIMEOUT 可选查询工具的执行超时秒数，默认 30。

CLICKHOUSE_MCP_SERVER_TRANSPORT 可选 MCP 传输方式：stdio（默认）、http 或 sse。

CLICKHOUSE_MCP_BIND_HOST 可选 HTTP/SSE 模式下 MCP 服务器监听地址，默认 127.0.0.1。

CLICKHOUSE_MCP_BIND_PORT 可选 HTTP/SSE 模式下 MCP 服务器监听端口，默认 8000。

CLICKHOUSE_MCP_AUTH_DISABLED 可选设为 true 可关闭 HTTP/SSE 认证，仅限本地开发。

FASTMCP_SERVER_AUTH 可选 FastMCP 认证提供者的完整类路径（如 Azure Entra），用于 OAuth/OIDC 认证。

CLICKHOUSE_SERVER_HOST_NAME 可选可选的 SNI 覆盖与证书校验主机名，用于代理/负载均衡场景。

CLICKHOUSE_PROXY_PATH 可选可选的 ClickHouse HTTP 端点 URL 路径前缀（反向代理场景）。

CLICKHOUSE_ENABLED 可选是否启用 ClickHouse 数据库工具，默认 true；仅用 chDB 时设为 false。

CHDB_ENABLED 可选是否启用 chDB 嵌入式引擎工具，默认 false，需安装 mcp-clickhouse[chdb]。

CHDB_DATA_PATH 可选 chDB 数据目录路径，默认 :memory:（内存模式）。

MCP_MIDDLEWARE_MODULE 可选包含自定义中间件的 Python 模块名（不含 .py），需提供 setup_middleware(mcp) 函数。

安装依赖：uv 或 Python。
在 Claude Desktop 配置文件中添加 mcpServers 条目（见 install_config）。
设置环境变量 CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD。
重启 Claude Desktop。

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_ROLE": "<clickhouse-role>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_ROLE": "<clickhouse-role>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add mcp-clickhouse -e 'CLICKHOUSE_HOST=<clickhouse-host>' -e 'CLICKHOUSE_PORT=<clickhouse-port>' -e 'CLICKHOUSE_USER=<clickhouse-user>' -e 'CLICKHOUSE_PASSWORD=<clickhouse-password>' -e 'CLICKHOUSE_ROLE=<clickhouse-role>' -e CLICKHOUSE_SECURE=true -e CLICKHOUSE_VERIFY=true -e CLICKHOUSE_CONNECT_TIMEOUT=30 -e CLICKHOUSE_SEND_RECEIVE_TIMEOUT=30 -- uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

在客户端工具列表中确认出现 run_query、list_databases、list_tables（以及可选的 run_chdb_select_query），然后让助手运行 SELECT 1 之类的查询，能返回结果即说明连接成功。

常见排障

检查 CLICKHOUSE_SECURE 和 CLICKHOUSE_PORT 是否匹配。
确保 CLICKHOUSE_PORT 是 HTTP 端口 (8123/8443)，而非 native TCP 端口 (9000/9440)。
查看服务器日志以获取详细错误信息。
确认 ClickHouse 服务可达且凭据正确。

试试这样问

连接成功后，可以直接对 AI 助手这样说：

列出 ClickHouse 集群上的所有数据库
显示数据库 default 里的所有表
对 ClickHouse 执行这条查询：SELECT version()
用 chDB 直接从这个 CSV 文件查询数据，不需要导入

工具能力 4

run_query 写入

在 ClickHouse 集群上执行 SQL 查询。默认只读。

list_databases 只读

列出 ClickHouse 集群上的所有数据库。

list_tables 只读

列出数据库中的表，支持分页和过滤。

run_chdb_select_query 只读

使用 chDB 的嵌入式 ClickHouse 引擎执行 SELECT 查询。

使用场景

让 AI 助手直接查询 ClickHouse 数据库以回答数据相关问题。

探索数据库结构，如表和数据库列表。

使用 chDB 进行本地数据分析，无需额外数据库。

支持客户端

Claude Desktop

依据项目文档列出，未经本站实测。

详细介绍

官方 ClickHouse MCP 服务器，用于查询和探索 ClickHouse 集群和 chDB。通过 MCP 提供 SQL 查询、数据库和表列表等工具。