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 概述