使用说明

项目简介

ClickHouse MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务端应用，旨在为大型语言模型 (LLM) 提供访问 ClickHouse 数据库的能力。通过提供 'connect_database' 和 'execute_query' 工具，LLM 可以安全地连接到 ClickHouse 数据库并执行 SQL 查询，从而获取和利用数据库中的数据信息。

主要功能点

连接 ClickHouse 数据库: 提供 'connect_database' 工具，允许 LLM 指定数据库名称并建立连接。
执行 SQL 查询: 提供 'execute_query' 工具，允许 LLM 执行 SQL 查询语句，并以 JSON 格式返回查询结果。
支持多查询执行: 'execute_query' 工具支持一次执行多条 SQL 查询语句（以分号分隔）。
灵活配置: 通过环境变量配置 ClickHouse 服务器连接信息，包括主机、端口、用户、密码和初始数据库。
只读模式: 支持配置只读模式，限制 LLM 对数据库的写操作，增强数据安全性。
基于 MCP 协议: 遵循 MCP 协议标准，易于与支持 MCP 协议的 LLM 客户端集成。

安装步骤

安装软件包: 使用 'pip' 或 'uv' 包管理器安装 'clickhouse-mcp-server' 软件包。

pip install clickhouse-mcp-server

或

uv pip install clickhouse-mcp-server

服务器配置

为了让 MCP 客户端（例如 Claude）能够连接到 'clickhouse-mcp-server'，您需要在客户端的配置文件中添加服务器配置信息。以下是配置示例 (以 Claude Desktop 为例)：

Claude Desktop 客户端配置 (claude_desktop_config.json):

{
  "mcpServers": {
    "clickhouse-mcp-server": {  // 服务器名称，客户端用此名称引用
      "command": "uvx",        // 运行服务器的命令，这里假设 clickhouse-mcp-server 已添加到系统路径中
      "args": [                // 命令参数
        "clickhouse-mcp-server" // 运行 clickhouse-mcp-server 的命令
      ],
      "env": {                 // 环境变量配置，用于连接 ClickHouse 数据库
        "CLICKHOUSE_HOST": "localhost",    // ClickHouse 服务器地址，默认为 localhost
        "CLICKHOUSE_USER": "default",      // ClickHouse 用户名，默认为 default
        "CLICKHOUSE_PASSWORD": "",         // ClickHouse 密码，默认为空
        "CLICKHOUSE_DATABASE": "[optional]", // 可选：初始连接的数据库
        "CLICKHOUSE_READONLY": "false"      // 是否启用只读模式，默认为 false
      }
    }
  }
}

配置说明:

'"clickhouse-mcp-server"': 服务器的唯一名称，在客户端配置中用于标识和引用此服务器。
'"command": "uvx"': 指定用于启动服务器的可执行命令。 'uvx' 通常用于运行通过 'uv' 安装的包，确保环境一致性。如果你的环境配置不同，可能需要调整为 'uv' 或 'python' 等，并指定入口脚本路径。
'"args": ["clickhouse-mcp-server"]': 传递给 'command' 的参数。这里 '"clickhouse-mcp-server"' 是 'clickhouse_mcp_server' 包提供的可执行入口点。
'"env": { ... }"': 设置服务器运行时需要的环境变量，这些变量用于配置 ClickHouse 数据库的连接信息。
- 'CLICKHOUSE_HOST', 'CLICKHOUSE_USER', 'CLICKHOUSE_PASSWORD', 'CLICKHOUSE_DATABASE': 用于配置 ClickHouse 数据库连接，请根据你的 ClickHouse 数据库实际情况修改。
- 'CLICKHOUSE_READONLY': 设置为 '"true"' 或 '"1"' 启用只读模式，设置为 '"false"' 或 '"0"' 禁用只读模式。

注意: 请根据你的实际 ClickHouse 服务器配置修改 'env' 中的环境变量值。确保 MCP 客户端能够正确加载并应用这些配置。

基本使用方法

启动 MCP 服务器: MCP 客户端（如 Claude）启动后，会自动尝试连接并启动配置中定义的 MCP 服务器。'clickhouse-mcp-server' 会在后台运行并等待客户端的请求。
在 LLM 中调用工具: 在支持 MCP 协议的 LLM 应用中，你可以通过指令或自然语言指示 LLM 调用 'clickhouse-mcp-server' 提供的工具，例如：
- 指示 LLM 使用 'connect_database' 工具连接到指定的 ClickHouse 数据库。
- 指示 LLM 使用 'execute_query' 工具执行 SQL 查询，并利用返回的数据进行后续操作。

示例对话 (假设在 Claude 中使用):

用户: "连接到数据库 'my_database' 并查询表 'users' 中的所有数据。"

Claude (内部操作):

Claude 客户端识别到用户请求需要访问数据库。
Claude 客户端调用 'clickhouse-mcp-server' 的 'connect_database' 工具，参数为 'database: "my_database"'。
连接成功后，Claude 客户端调用 'clickhouse-mcp-server' 的 'execute_query' 工具，参数为 'query: "SELECT * FROM users;"'。
'clickhouse-mcp-server' 执行查询并将结果返回给 Claude 客户端。
Claude 客户端将查询结果整合到回复中，返回给用户。

用户: "查询 'orders' 表中订单金额大于 1000 的订单数量。"