使用说明

项目简介

ClickHouse MCP Server 是一个基于 Model Context Protocol (MCP) 标准构建的服务器，它充当 LLM（如 Claude）与 ClickHouse 数据库之间的桥梁。通过此服务器，LLM 可以安全地探索 ClickHouse 数据库中的数据，并执行只读 SQL 查询进行数据分析。

主要功能点

数据源连接: 连接到 ClickHouse 数据库。
资源浏览: 将 ClickHouse 数据库的表结构和示例数据以资源的形式暴露给 LLM，方便 LLM 理解数据上下文。
SQL 查询工具: 提供执行只读 SQL 查询的工具，允许 LLM 基于自然语言指令查询和分析数据。
自然语言查询: 支持通过自然语言提问，辅助 LLM 理解数据表结构，并生成 SQL 查询。
兼容 Claude Desktop: 特别为 macOS 上的 Claude Desktop 设计，方便集成使用。

安装步骤

克隆仓库

git clone https://github.com/bjpadhy/clickhouse-mcp-server.git
cd clickhouse-mcp-server

安装依赖
```
npm install
```

配置环境变量

在项目根目录下创建 '.env' 文件，并参考 '.env.example' 填写 ClickHouse 数据库连接信息。务必使用只读数据库用户，以确保数据安全。

CLICKHOUSE_URL=your_clickhouse_url
CLICKHOUSE_USERNAME=your_username
CLICKHOUSE_PASSWORD=your_password
CLICKHOUSE_DATABASE=your_database

构建项目
```
npm run build
```

服务器配置

要将 ClickHouse MCP Server 集成到 MCP 客户端（例如 Claude Desktop），您需要配置客户端以连接到此服务器。以下是 Claude Desktop 的配置示例，您需要将此配置添加到 Claude Desktop 的配置文件 'claude_desktop_config.json' 中。

{
  "mcpServers": {
    "clickhouse-analytics": {  // 服务器名称，可以自定义
      "command": "node",      // 启动服务器的命令，这里使用 node 运行 JavaScript 文件
      "args": [              // 启动命令的参数
        "/absolute/path/to/clickhouse-mcp-server/dist/index.js" //  'index.js' 文件的绝对路径，请替换为实际路径
      ],
      "env": {               // 环境变量，传递数据库连接信息
        "CLICKHOUSE_URL": "your_clickhouse_url",        // ClickHouse 服务器 URL，请替换为实际值
        "CLICKHOUSE_USERNAME": "your_username",      // ClickHouse 用户名，请替换为实际值
        "CLICKHOUSE_PASSWORD": "your_password",      // ClickHouse 密码，请替换为实际值
        "CLICKHOUSE_DATABASE": "your_database"        // ClickHouse 数据库名，请替换为实际值
      }
    }
  }
}

请注意：

'/absolute/path/to/clickhouse-mcp-server/dist/index.js' 需要替换为 'index.js' 文件在您本地文件系统中的绝对路径。
'your_clickhouse_url', 'your_username', 'your_password', 'your_database' 需要替换为您的 ClickHouse 数据库的实际连接信息。
'server name' (例如 "clickhouse-analytics") 可以自定义，用于在 MCP 客户端中标识和选择此服务器。

基本使用方法

启动服务器 在项目根目录下运行：
```
npm start
```
服务器将在 stdio 上运行，等待 MCP 客户端连接。
配置并重启 MCP 客户端 根据上述 "服务器配置" 部分，配置您的 MCP 客户端（例如 Claude Desktop），并重启客户端使配置生效。
在 MCP 客户端中使用 在 MCP 客户端中，您应该能够看到已配置的 "clickhouse-analytics" 服务器。您可以使用以下资源和工具与 ClickHouse 数据库进行交互：

资源 (Resources):
- 'db://info': 获取数据库信息，包括表和结构。
- 'table://{tableName}/schema': 获取指定表的结构信息，将 '{tableName}' 替换为实际表名。
- 'table://{tableName}/sample': 获取指定表的示例数据（前5行），将 '{tableName}' 替换为实际表名。
工具 (Tools):
- 'execute-sql': 执行 SQL 查询。在客户端中调用此工具时，需要提供 'query' 参数，即要执行的 SQL 查询语句（只允许只读查询）。
- 'natural-language-query': 自然语言查询。您可以向 LLM 提出关于数据的问题，服务器会返回数据库结构信息以帮助 LLM 理解数据，并提示可以使用 'execute-sql' 工具执行 SQL 查询。

安全提示:

请务必使用只读数据库用户配置 ClickHouse 连接，避免误操作导致数据修改或删除。
仔细审查 LLM 生成的 SQL 查询，确保其安全性后再执行。

关键词