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（admin），每条语句由分类结果把关。

• 访问模式 — read-only → read-write → admin 分层，每种模式都不会暴露其级别之上的语句。

• 安全标志 — 数据库允许列表、受保护数据库、破坏性操作门控、行数上限、试运行和 JSON 审计日志（见下文）。

Related MCP server: clickhouse-mcp-server

安全模型

语句分类逻辑位于 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 — 对单条语句分类后再执行；写入需要 read-write 模式，破坏性语句需要 admin 模式及 CLICKHOUSE_ALLOW_DELETE。

配合你的 MCP 客户端使用

可与 Claude Code、Claude Desktop、Cursor、OpenAI Codex CLI、Windsurf、VS Code (Copilot) 以及任何其他 MCP 客户端配合使用 — 各客户端的配置方式请参阅 docs/CLIENTS.md。

安装

npm install
npm run build

使用 Claude Desktop / Claude Code 运行

{
  "mcpServers": {
    "clickhouse": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-clickhouse/dist/index.js"],
      "env": {
        "CLICKHOUSE_URL": "http://clickhouse:8123",
        "CLICKHOUSE_USER": "readonly",
        "CLICKHOUSE_PASSWORD": "…",
        "CLICKHOUSE_MODE": "read-only",
        "CLICKHOUSE_DATABASE_ALLOWLIST": "analytics"
      }
    }
  }
}

示例提示

• "在 analytics 数据库中，哪些表最大？"

• "展示 events 表的表结构，并运行一个查询本周每日计数的查询。"

• "哪些查询正在运行且占用内存最多？"

开发

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

发布

本服务器附带了 server.json 用于官方 MCP 注册表，以及 mcpName 用于 npm 所有权验证。有关发布到 npm 以及在 MCP 注册表、Smithery、Glama、Cursor 和 PulseMCP 上列的详细信息，请参阅 PUBLISHING.md。

许可证

MIT