ClickHouse MCP Server 使用说明

项目简介

ClickHouse MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为大型语言模型（LLM）客户端提供访问和操作 ClickHouse 数据库的能力。通过此服务器，LLM 可以安全、便捷地查询 ClickHouse 中的数据，并获取数据库的结构信息。

主要功能点

执行 SQL 查询: 允许 LLM 客户端向 ClickHouse 数据库发送 SQL SELECT 查询，并获取查询结果。所有查询均以只读模式执行，保障数据安全。
列出数据库: 提供查看 ClickHouse 服务器上所有数据库名称的功能。
列出数据表: 允许 LLM 客户端查看指定数据库中的所有数据表，并获取表的结构信息，包括列名、数据类型和注释等。

安装步骤

安装 'uv': 按照 uv 安装指南安装 'uv' 包管理器。
同步依赖: 在仓库根目录下运行 'uv sync' 命令安装项目依赖。
激活虚拟环境: 运行 'source .venv/bin/activate' 命令激活虚拟环境。

服务器配置

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

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<您的ClickHouse主机地址>",  // **[必填]**：您的 ClickHouse 服务器主机名或 IP 地址
        "CLICKHOUSE_PORT": "<您的ClickHouse端口>",      // **[可选]**：您的 ClickHouse 服务器端口号，默认为 8443 (HTTPS) 或 8123 (HTTP)
        "CLICKHOUSE_USER": "<您的ClickHouse用户名>",      // **[必填]**：用于连接 ClickHouse 的用户名
        "CLICKHOUSE_PASSWORD": "<您的ClickHouse密码>",  // **[必填]**：用于连接 ClickHouse 的密码
        "CLICKHOUSE_SECURE": "true",                   // **[可选]**：是否启用 HTTPS 连接，默认为 "true"
        "CLICKHOUSE_VERIFY": "true",                   // **[可选]**：是否验证 SSL 证书，默认为 "true"
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",           // **[可选]**：连接超时时间，单位秒，默认为 "30"
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "300"      // **[可选]**：发送/接收超时时间，单位秒，默认为 "300"
      }
    }
  }
}

配置说明:

请将 '<您的ClickHouse主机地址>'、'<您的ClickHouse端口>'、'<您的ClickHouse用户名>' 和 '<您的ClickHouse密码>' 替换为您的实际 ClickHouse 数据库连接信息。
如果您的 'uv' 命令不在系统 PATH 环境变量中，您需要将 '"command": "uv"' 替换为 'uv' 可执行文件的绝对路径（可以使用 'which uv' 命令查找）。
根据您的 ClickHouse 服务器配置，您可以调整 'env' 中的其他可选参数，例如端口、安全设置和超时时间。

基本使用方法

配置完成后，重启您的 MCP 客户端。客户端将能够通过 MCP 协议与 ClickHouse MCP Server 通信，并使用以下工具：

'list_databases': 列出 ClickHouse 服务器上的所有数据库。
'list_tables': 列出指定数据库中的所有表，并获取表的详细信息（包括列和注释）。
'run_select_query': 执行 SQL SELECT 查询并返回结果。

具体使用方法请参考您的 MCP 客户端（如 Claude）的文档，在客户端中选择相应的工具并提供必要的参数（例如，执行 SQL 查询时需要提供 SQL 查询语句）。

关键词