MCP Clickhouse

🚀 ClickHouse MCP Server

ClickHouse MCP Server 是一个用于 ClickHouse 的 MCP 服务器，可帮助用户在 ClickHouse 集群上执行各类操作，如执行 SQL 查询、列出数据库和表等。

✨ 主要特性

工具

• run_select_query

  • 在你的 ClickHouse 集群上执行 SQL 查询。
  • 输入：sql（字符串）：要执行的 SQL 查询语句。
  • 所有 ClickHouse 查询都以 readonly = 1 运行，以确保安全性。

• list_databases

  • 列出你的 ClickHouse 集群上的所有数据库。

• list_tables

  • 列出数据库中的所有表。
  • 输入：database（字符串）：数据库的名称。

📦 安装指南

配置步骤

1. 打开 Claude Desktop 配置文件，其位置如下：

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

2. 添加以下内容：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "1800",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "1800"
      }
    }
  }
}

将环境变量更新为指向你自己的 ClickHouse 服务。

或者，如果你想使用 ClickHouse SQL Playground 进行测试，可以使用以下配置：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "1800",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "1800"
      }
    }
  }
}

3. 找到 uv 的命令入口，并将其替换为 uv 可执行文件的绝对路径。这样可以确保在启动服务器时使用正确版本的 uv。在 Mac 上，你可以使用 which uv 找到该路径。

4. 重启 Claude Desktop 以应用更改。

🔧 技术细节

开发步骤

1. 在 test-services 目录中运行 docker compose up -d 以启动 ClickHouse 集群。

2. 将以下变量添加到仓库根目录的 .env 文件中。

注意：在此上下文中使用 default 用户仅用于本地开发目的。

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

3. 运行 uv sync 以安装依赖项。要安装 uv，请遵循 此处 的说明。然后执行 source .venv/bin/activate。

4. 为了方便测试，你可以运行 mcp dev mcp_clickhouse/mcp_server.py 来启动 MCP 服务器。

环境变量

以下环境变量用于配置 ClickHouse 连接：

必需变量

• CLICKHOUSE_HOST：你的 ClickHouse 服务器的主机名
• CLICKHOUSE_USER：用于身份验证的用户名
• CLICKHOUSE_PASSWORD：用于身份验证的密码

⚠️ 重要提示

重要的是要像对待任何连接到你数据库的外部客户端一样对待你的 MCP 数据库用户，仅授予其操作所需的最小必要权限。应始终严格避免使用默认或管理员用户。

可选变量

• CLICKHOUSE_PORT：你的 ClickHouse 服务器的端口号
  • 默认值：如果启用 HTTPS，则为 8443；如果禁用，则为 8123
  • 通常，除非使用非标准端口，否则不需要设置此变量
• CLICKHOUSE_SECURE：启用/禁用 HTTPS 连接
  • 默认值："true"
  • 设置为 "false" 以进行非安全连接
• CLICKHOUSE_VERIFY：启用/禁用 SSL 证书验证
  • 默认值："true"
  • 设置为 "false" 以禁用证书验证（不建议在生产环境中使用）
• CLICKHOUSE_CONNECT_TIMEOUT：连接超时时间（秒）
  • 默认值："1800"
  • 如果你遇到连接超时问题，可以增加此值
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT：发送/接收超时时间（秒）
  • 默认值："1800"
  • 对于长时间运行的查询，可以增加此值
• CLICKHOUSE_DATABASE：要使用的默认数据库
  • 默认值：无（使用服务器默认值）
  • 设置此变量可自动连接到特定数据库

示例配置

对于使用 Docker 进行本地开发：

# 必需变量
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# 可选：覆盖本地开发的默认值
CLICKHOUSE_SECURE=false  # 自动使用端口 8123
CLICKHOUSE_VERIFY=false

对于 ClickHouse Cloud：

# 必需变量
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# 可选：使用安全默认值
# CLICKHOUSE_SECURE=true  # 自动使用端口 8443
# CLICKHOUSE_DATABASE=your_database

对于 ClickHouse SQL Playground：

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# 使用安全默认值（端口 8443 上的 HTTPS）

你可以在环境中、.env 文件中或 Claude Desktop 配置中设置这些变量：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>"
      }
    }
  }
}

运行测试

uv sync --all-extras --dev # 安装开发依赖项
uv run ruff check . # 运行代码检查

docker compose up -d test_services # 启动 ClickHouse
uv run pytest tests

📚 详细文档

YouTube 概述