mcp-clickhouse

mcp-clickhouse

一个用于 ClickHouse 的 Model Context Protocol 服务。它允许支持 MCP 的客户端（Claude Desktop、Claude Code 等）探索架构、运行分析查询并管理数据库，所有行为均由标志控制。

安全模型感知语句类型：每条 SQL 语句都会被归类为读取、写入或破坏性操作，并根据当前访问模式进行限制。只读模式还会使用 ClickHouse 自身的 readonly=1 设置来运行查询。

功能

• 探索与监控——数据库、表、列、SHOW CREATE、表统计信息（分区、行数、字节数）、运行中的查询、服务器指标、集群拓扑。
• 读取查询——query 工具仅接受读取语句，并将结果限制在 CLICKHOUSE_MAX_ROWS。
• 管理——execute 工具用于执行 INSERT/CREATE/ALTER（读写模式）和 DROP/TRUNCATE/DELETE（管理员模式），每项操作都会根据分类进行限制。
• 访问模式——read-only → read-write → admin，逐级开放，确保某种模式不会允许执行超出其级别的语句。
• 安全标志——数据库允许列表、受保护的数据库、破坏性操作限制、行数上限、试运行和 JSON 审计日志（见下文）。

安全模型

关注点	标志	默认值	效果
服务可以执行哪些操作？	CLICKHOUSE_MODE	read-only	read-only 仅开放读取工具（并在 query 中拒绝非 SELECT 语句）；read-write 会为写入开放 execute；admin 允许破坏性语句。
哪些数据库在操作范围内？	CLICKHOUSE_DATABASE_ALLOWLIST	(全部)	设置后，将拒绝对其他数据库执行操作。
哪些数据库始终为只读？	CLICKHOUSE_PROTECTED_DATABASES	system,information_schema	可读取，但永远不能修改。
是否可以运行破坏性 SQL？	CLICKHOUSE_ALLOW_DELETE	false	DROP/TRUNCATE/DELETE/… 需要启用此项并且处于管理员模式。
结果大小上限	CLICKHOUSE_MAX_ROWS	1000	限制返回给模型的行数。
预览而不执行	CLICKHOUSE_DRY_RUN	false	写入/破坏性语句会进行验证并记录意图，然后返回。
审计跟踪	CLICKHOUSE_AUDIT_LOG	true	每次受限制的操作都会向 stderr 输出一行 JSON。
交互式确认	(自动)	—	运行破坏性和高影响操作前，会通过 MCP elicitation 请求人工批准；不支持 elicitation 的客户端会回退到 *_ALLOW_* 限制。

语句分类逻辑位于 src/sql.ts 中，并采用故障安全策略：ALTER … DELETE/UPDATE 视为破坏性操作，任何无法解析的语句也会被视为破坏性操作。

工具

读取（read-only+）：list_databases、list_tables、describe_table、show_create_table、table_stats、running_queries、server_metrics、cluster_info、query

写入/管理员（read-write+）：execute——对单条语句进行分类后运行；写入需要读写模式，破坏性语句需要管理员模式和 CLICKHOUSE_ALLOW_DELETE。

快速入门 — 添加到你的 Agent

已发布到 npm，包名为 @dockndevai/mcp-clickhouse。无需克隆或构建 — MCP 客户端会按需通过 npx 运行它。请从 read-only 模式开始；所有变量请参阅 .env.example，各客户端的完整指南请参阅 docs/CLIENTS.md。

Claude Code（命令行）

claude mcp add clickhouse -e CLICKHOUSE_URL="http://localhost:8123" -e CLICKHOUSE_USER="default" -e CLICKHOUSE_MODE="read-only" -- npx -y @dockndevai/mcp-clickhouse

Claude Desktop · Cursor · Windsurf — 将同一代码块添加到 claude_desktop_config.json、.cursor/mcp.json 或 ~/.codeium/windsurf/mcp_config.json 中：

{
  "mcpServers": {
    "clickhouse": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_URL": "http://localhost:8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — 在 ~/.codex/config.toml 中：

[mcp_servers.clickhouse]
command = "npx"
args = ["-y", "@dockndevai/mcp-clickhouse"]
env = { CLICKHOUSE_URL = "http://localhost:8123", CLICKHOUSE_USER = "default", CLICKHOUSE_MODE = "read-only" }

VS Code（GitHub Copilot，Agent 模式） — 在 .vscode/mcp.json 中：

{
  "servers": {
    "clickhouse": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_URL": "http://localhost:8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_MODE": "read-only"
      }
    }
  }
}

示例提示词

• “analytics 数据库中最大的表有哪些？”
• “显示 events 的架构，并运行查询统计本周每天的数据量。”
• “当前有哪些查询正在运行并占用最多内存？”

从源代码运行（开发）

建议使用上文发布的包。若要从克隆的仓库运行：

npm install
npm run build
node dist/index.js   # with the environment variables set

开发

npm run dev
npm test          # SQL classification + security policy (30 tests)
npm run typecheck

发布

此服务提供用于官方 MCP 注册表的 server.json，以及用于 npm 所有权验证的 mcpName。有关发布到 npm 并上架 MCP 注册表、Smithery、Glama、Cursor 和 PulseMCP 的说明，请参阅 PUBLISHING.md。

许可证

MIT