ClickHouse

MCP ClickHouse 工具

一个默认只读的 ClickHouse 模型上下文协议（MCP）服务，提供架构发现、只读查询、执行计划分析、选择启用的写入，以及通过基于配置档案的方式，从单次工具集部署访问多个服务。

只读限制由引擎强制执行，而不是通过匹配 SQL 文本实现：查询工具使用的客户端会携带 ClickHouse 的 readonly=1，因此写入、外部表函数和查询级 SETTINGS 都会被所查询的服务拒绝。写入功能由单独的工具提供，只有在配置档案要求启用时才会注册。

要求： Python 3.13+、正在运行的 ClickHouse 实例，以及通过环境变量或配置文件提供的连接详情。

快速开始

设置 DSN，并通过 MCP Inspector 运行服务：

# Option 1: Run directly with uvx (no clone needed)
export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default"
npx -y @modelcontextprotocol/inspector@latest uvx mcp-clickhousex

# Option 2: Run from source (clone repo, then)
export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default"
npx -y @modelcontextprotocol/inspector@latest uv run mcp-clickhousex

配置

配置档案是一条 ClickHouse 连接：一个 DSN，以及适用于该连接的行数和超时上限。名为 default 的配置档案始终存在；每个工具都可以使用可选的 profile 访问其他配置档案，list_profiles 会报告已配置的内容。

设置来自三个来源，并按字段合并，后者优先：

1. 用户级 config.json — 可包含任意数量的配置档案；
2. MCP_CLICKHOUSE_PROFILES_<NAME>_<FIELD> 环境变量 — 可包含任意数量的配置档案；
3. 扁平的 MCP_CLICKHOUSE_<FIELD> 环境变量 — 仅用于 default 配置档案。

由于合并按字段而非按配置档案进行，config.json 可以包含完整配置，同时使用扁平的 MCP_CLICKHOUSE_DSN 将默认配置档案重新指向本地服务，并保留其其他字段不变。如果这三个来源均不存在，default 将回退到 http://default:@localhost:8123/default。

每项设置只有一个字段名，有三种写法 — MCP_CLICKHOUSE_<FIELD>、MCP_CLICKHOUSE_PROFILES_<NAME>_<FIELD>，或作为 JSON 键的小写字段名：

上限按配置档案分别生效。超过上限的值会在启动时被截断；不是整数的值会回退到默认值，而不是布尔值的值会使 ALLOW_WRITE 保持关闭。

**单条连接：**扁平环境变量是最简便的方式。

# Connection DSN.
export MCP_CLICKHOUSE_DSN="http://user:password@host:8123/database"

# Optional description for the default profile (tooling/AI discovery).
export MCP_CLICKHOUSE_DESCRIPTION="Primary cluster"

# Optional caps, defaults shown.
export MCP_CLICKHOUSE_QUERY_MAX_ROWS="500"
export MCP_CLICKHOUSE_QUERY_COMMAND_TIMEOUT_SECONDS="30"
export MCP_CLICKHOUSE_SNAPSHOT_MAX_ROWS="10000"
export MCP_CLICKHOUSE_SNAPSHOT_COMMAND_TIMEOUT_SECONDS="120"

# Optional write access, off by default; also controls whether run_command
# is advertised at all.
export MCP_CLICKHOUSE_ALLOW_WRITE="false"
export MCP_CLICKHOUSE_WRITE_COMMAND_TIMEOUT_SECONDS="60"

**多条连接：**使用用户级 config.json，这样凭据就不会出现在宿主的进程环境中。

• 类 Unix 系统：~/.config/mcp-clickhousex/config.json
• Windows：%USERPROFILE%\.config\mcp-clickhousex\config.json

{
  "profiles": {
    "default": {
      "dsn": "http://default:@localhost:8123/default",
      "description": "Primary",
      "query_max_rows": 500,
      "query_command_timeout_seconds": 60,
      "snapshot_max_rows": 10000,
      "snapshot_command_timeout_seconds": 120
    },
    "warehouse": {
      "dsn": "http://user:pass@warehouse:8123/analytics",
      "description": "Warehouse"
    },
    "writer": {
      "dsn": "http://etl:pass@warehouse:8123/analytics",
      "description": "Warehouse, write-enabled",
      "allow_write": true,
      "write_command_timeout_seconds": 120
    }
  }
}

一个配置档案既可以读取也可以写入，但更值得借鉴的做法是单独设置一个启用了写入的配置档案：这样写入操作就有自己的 DSN，其凭据可以限定为实际所需的权限，而读取配置档案则继续使用授权仅限于 SELECT 的登录账号。

配置档案名称不区分大小写，且必须为字母数字 — 不能包含下划线或连字符，因为结构化环境变量格式会按 _ 分隔（MCP_CLICKHOUSE_PROFILES_WAREHOUSE_DSN 表示配置档案 warehouse，字段为 DSN）。不符合此规则的名称会被跳过；缺失、无法读取或格式不是 {"profiles": {…}} 的 config.json 也会被跳过。服务会使用剩余可用来源启动，而不会报错退出。

DSN 语法：scheme://user:password@host:port/database。https:// 或 clickhouses:// 协议会启用 TLS，查询字符串参数会传递给驱动（?connect_timeout=10）— 但 readonly 除外，服务始终会根据配置档案的 ALLOW_WRITE 最后应用该参数。

用户名或密码中的 URL 保留字符必须进行百分号编码 — # → %23、? → %3F、/ → %2F、@ → %40、% → %25。用户名为 admin@org、密码为 p#ss? 时，应写作 http://admin%40org:p%23ss%3F@host:8123/database。

工具和资源

所有工具都接受可选的 profile；省略时使用默认配置。

工具

• types — EXPLAIN 变体：plan（索引）、pipeline、syntax。默认使用 plan 和 pipeline。
• parameters — 驱动程序占位符的命名参数，格式为 %(name)s 或 {name:Type}。
• database — 未限定名称时使用的会话默认数据库；否则请使用 db.table。

目录发现没有专用工具：使用 run_query 查询 system.databases、system.tables 和 system.columns，列出数据库、表和列，并读取大小（total_rows、total_bytes）及键（primary_key、sorting_key、partition_key）。这些表支持常规 WHERE 谓词，而 SHOW 仅支持 LIKE。SHOW 适用于列表查询无法提供的 DDL 信息：使用 SHOW CREATE TABLE/VIEW/DICTIONARY 查看编解码器、TTL 和完整列清单。

结果为 RFC 4180 CSV：第一行为表头，其余为数据。NULL 会写作 \N，这是 ClickHouse 自身的 CSV 空值表示方式，因此可与空字符串区分开来。

计划中的 Indexes 部分不能作为表键的权威信息：它只列出查询使用的键列，因此，跳过首个键列的查询会报告一个比表实际键更短的键。请通过 system.tables 确认；它只需几十个 token 就能给出答案，而 SHOW CREATE TABLE 要花上几百个 token 才能说明同样的内容。

调用所适用的行数上限会随结果一并返回，字段为 truncated 和 row_limit。

资源

安全性

此服务打开的每个客户端都带有 ClickHouse 自身的 readonly=1，因此引擎（而不只是服务的 SQL 检查）会拒绝：

• 任何形式的写入（INSERT、DDL、ALTER … UPDATE、SYSTEM、GRANT）；
• 外部表函数 url()、s3()、remote()、mysql() 等，因此查询无法访问配置文件以外的主机；
• 查询级 SETTINGS，因此 Agent 提供的 SQL 无法提高行数和时间上限，INTO OUTFILE 也会被拒绝。

我们有意不使用 readonly=2：它允许更改 SETTINGS，会让这些上限形同虚设。代价是，连无害的单次查询调优（SETTINGS max_threads = …）也会被拒绝。

除此之外，run_query 只接受 SELECT / WITH … SELECT / SHOW，而 analyze_query 只接受前两种；每次调用只能执行一条语句。交互式查询会强制执行严格的行数上限（默认 500，硬上限 1 000）；如需提取更多数据，请使用 snapshot=true（默认 10 000，硬上限 50 000）。

写入默认关闭，启用前不可见。 run_command 使用带有 readonly=0 的客户端运行，因此可以执行任意 DDL 和 DML；取消 readonly 限制后，外部表函数也会重新开放。除非至少有一个已配置的配置文件将 ALLOW_WRITE 设为启用（默认 false），否则根本不会注册此工具：它不会出现在 tools/list 中，因此只读部署无需为它消耗上下文，也不会向 Agent 提供可能被诱导使用的写入入口。一旦有任意配置文件选择启用，此工具就会在整个服务中公布，但对于仍处于锁定状态的配置文件，调用时仍会被拒绝；list_profiles 会报告每个配置文件的 allow_write，以便 Agent 选择可写配置文件。

ALLOW_WRITE 是应用层的软性防护，不是安全边界——它约束的是此服务，而不是数据库。要真正保证只读，请使用权限仅限于 SELECT 的 ClickHouse 登录凭据进行连接，并确保启用了写入的配置文件只使用权限范围符合其需求的凭据。run_command 带有 destructive 和 openWorld 工具注解，供宿主在执行前要求确认，但是否遵循这些注解由宿主决定。ClickHouse 在此处没有可用于回滚的事务：语句一旦执行成功，就会永久生效。

请使用环境变量或配置文件存储连接凭据，切勿提交密钥。

MCP 宿主示例

以下代码片段使用 uvx mcp-clickhousex（无需克隆；请确保 uv 位于 PATH 中）。请按需替换连接详情；如果 DSN 已来自 config.json 或环境，则不需要 env 块。

Claude Code 和 Cursor 使用相同的 mcpServers 格式：

{
  "mcpServers": {
    "clickhouse": {
      "command": "uvx",
      "args": ["mcp-clickhousex"],
      "env": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

[mcp_servers.clickhouse]
command = "uvx"
args = ["mcp-clickhousex"]

[mcp_servers.clickhouse.env]
MCP_CLICKHOUSE_DSN = "http://default:@localhost:8123/default"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "clickhouse": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "mcp-clickhousex"],
      "environment": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

{
  "inputs": [],
  "servers": {
    "clickhouse": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-clickhousex"],
      "env": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

测试

测试需要有正在运行的 ClickHouse 实例；测试套件会在默认数据库中创建一个示例表，为其填充数据，并在测试后删除。

uv run pytest tests/ -v

测试框架通过 MCP_TEST_CLICKHOUSE_DSN 查找实例，如果未设置，则使用 http://admin:password123@localhost:8123/default。将其设为其他服务器的地址，即可让测试指向另一台服务器，而无需改动生产环境中的 MCP_CLICKHOUSE_DSN。

测试套件会在该实例上配置两个配置文件——只读的 default 和启用了写入的 writable——以测试写入限制的两方面：由于有配置文件选择启用，run_command 会被公布；但在不允许写入的配置文件上调用时，仍会被拒绝。

贡献

欢迎提交 issue 或 PR；请遵循现有风格，并酌情添加测试。

许可证

MIT