ClickHouse/mcp-clickhouse

解决的问题

此项目提供一个 Model Context Protocol (MCP) 服务器，允许 AI 助手（如 Claude Desktop）直接与 ClickHouse 数据库交互。它弥合了 LLM 与存储在 ClickHouse 中的结构化数据之间的差距，使 AI 能够查询、探索和分析数据，而无需用户手动导出文件或自行编写每个查询。

运作方式

此服务器作为中介，将特定的 ClickHouse 工具暴露给兼容 MCP 的客户端。它支持两种操作模式：连接到远程 ClickHouse 集群，或使用 chDB（一种嵌入式 ClickHouse 引擎）直接从文件或 URL 查询数据，无需 ETL 流程。

主要功能包括：

• 查询执行：执行 SQL 查询，支持命名参数以防止 SQL 注入并处理复杂类型。
• 数据库探索：列出数据库和表（支持分页和过滤），帮助 AI 理解结构。
• 查询检查：使用 DESCRIBE 检查结果结构，并使用 EXPLAIN ESTIMATE 在执行前预测查询的资源成本。
• 安全性：默认启用只读模式，并为 HTTP/SSE 传输提供多种认证方法（静态 Bearer 令牌或 OAuth/OIDC）。

适用对象

• 数据分析师和工程师：希望使用 AI 探索 ClickHouse 中的大型数据集。
• AI 应用程序开发者：希望让其 LLM 代理能够从 ClickHouse 数据库执行实时数据检索。
• DevOps 工程师：需要将 ClickHouse 数据访问集成到基于 MCP 的 AI 生态系统中。

亮点

• 双引擎支持：同时适用于完整的 ClickHouse 集群和嵌入式 chDB 引擎。
• 安全探索：默认只读访问，并提供估算查询成本的工具，以防止昂贵的扫描。
• 安全参数化：使用 {name:Type} 占位符进行安全且精确的数据绑定。
• 企业级认证：通过 FastMCP 支持各种 OIDC 提供商，适用于生产部署。