ClickHouse MCP 服务器

一个模型上下文协议 (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