ClickHouse MCP 服务器

一个 Model Context Protocol (MCP) 服务器，连接到 ClickHouse 数据库，并允许大型语言模型（如 Claude）通过自然语言查询探索和分析数据。

功能

• 连接到 ClickHouse 数据库
• 暴露表架构作为资源
• 从自然语言指令运行 SQL 查询
• 执行只读 SQL 查询
• 与 macOS 上的 Claude Desktop 配合使用

演示

https://github.com/user-attachments/assets/b496b9b0-5955-49d5-8c26-733f34662d8f

安装

1. 克隆此仓库
2. 安装依赖项：

npm install

3. 在 .env 文件中配置环境变量（参考 .env.example）。请确保使用只读数据库用户以限制 DDL 和 DML 执行
4. 构建项目：

npm run build

使用方法

本地运行服务器

npm start

与 Claude Desktop 集成

1. 创建或更新你的 Claude Desktop 配置文件：

   • 在 macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json

2. 添加服务器配置：

{
  "mcpServers": {
    "clickhouse-analytics": {
      "command": "node",
      "args": [
        "/absolute/path/to/clickhouse-mcp-server/dist/index.js"
      ],
      "env": {
        "CLICKHOUSE_URL": "your_clickhouse_url",
        "CLICKHOUSE_USERNAME": "your_username",
        "CLICKHOUSE_PASSWORD": "your_password",
        "CLICKHOUSE_DATABASE": "your_database"
      }
    }
  }
}

3. 重新启动 Claude Desktop

可用功能

资源

• db://info - 数据库信息，包括表和架构
• table://{tableName}/schema - 特定表的架构
• table://{tableName}/sample - 特定表的样本数据（5 行）

工具

• execute-sql - 对数据库执行只读 SQL 查询
• natural-language-query - 以自然语言形式提问关于数据的问题

安全注意事项

• 此服务器仅允许执行只读 SQL 查询
• 敏感凭证应安全地存储在环境变量中
• 服务器执行基本验证以防止 DDL 或 DML 语句的执行
• 请始终在执行查询请求前进行审查

许可证

MIT