ClickHouse

官方

查詢您的 ClickHouse 資料庫伺服器。

GitHub

839

你可以用 Click House MCP 做什麼？

執行唯讀 SQL 查詢 — 要求助理使用 run_query 對您的 ClickHouse 叢集執行任何 SELECT 查詢。
列出資料庫與資料表 — 透過 list_databases 列出所有資料庫，或使用 list_tables 分頁瀏覽特定資料庫中的資料表，藉此探索您的結構描述。
透過 chDB 直接查詢檔案與 URL — 使用 run_chdb_select_query 對本機檔案或遠端資料來源執行 SQL，無需先將資料載入 ClickHouse。
控制寫入與破壞性操作 — 啟用 CLICKHOUSE_ALLOW_WRITE_ACCESS 以允許 DDL/DML 操作，並可選擇啟用 CLICKHOUSE_ALLOW_DROP，讓 AI 輔助工作階段中允許執行 DROP 或 TRUNCATE 陳述式。

文件

ClickHouse MCP 伺服器

一個適用於 ClickHouse 的 MCP 伺服器。

功能特色

ClickHouse 工具

run_query
- 在您的 ClickHouse 叢集上執行 SQL 查詢。
- 輸入：query (字串)：要執行的 SQL 查詢。
- 查詢預設以唯讀模式執行 (CLICKHOUSE_ALLOW_WRITE_ACCESS=false)，但如有需要，可以明確啟用寫入功能。
list_databases
- 列出您 ClickHouse 叢集上的所有資料庫。
list_tables
- 以分頁方式列出資料庫中的表格。
- 必要輸入：database (字串)。
- 可選輸入：
  - like / not_like (字串)：對表格名稱套用 LIKE 或 NOT LIKE 篩選條件。
  - page_token (字串)：前一次呼叫所回傳、用於取得下一頁的權杖。
  - page_size (整數，預設值 50)：每頁回傳的表格數量。
  - include_detailed_columns (布林值，預設值 true)：當設為 false 時，會省略欄位中繼資料以獲得更輕量的回應，同時保留完整的 create_table_query。
- 回應結構：
  - tables：目前頁面的表格物件陣列。
  - next_page_token：傳回此值以取得下一頁，若已無更多表格則為 null。
  - total_tables：符合所提供篩選條件的表格總數。

chDB 工具

run_chdb_select_query
- 使用 chDB 的嵌入式 ClickHouse 引擎執行 SQL 查詢。
- 輸入：query (字串)：要執行的 SQL 查詢。
- 直接從各種來源（檔案、網址、資料庫）查詢資料，無需 ETL 流程。
- 需要可選的 chdb 附加套件：pip install 'mcp-clickhouse[chdb]'

健康檢查端點

當使用 HTTP 或 SSE 傳輸方式執行時，可於 /health 使用健康檢查端點。此端點：

若伺服器健康且能連線至 ClickHouse，則回傳 200 OK（主體：OK）
若伺服器無法連線至 ClickHouse，則回傳 503 Service Unavailable 並附上一般錯誤訊息

此端點刻意設計為無需驗證，以便協調器探測（例如 Kubernetes 的存活/就緒探測、負載平衡器）無需憑證即可存取。回應主體刻意保持精簡，以避免洩漏後端版本字串或錯誤細節；請透過伺服器日誌來偵錯失敗狀況。

範例：

curl http://localhost:8000/health
# Response: OK

安全性

HTTP/SSE 傳輸的驗證

使用 HTTP 或 SSE 傳輸時，預設需要驗證。stdio 傳輸方式（預設）僅透過標準輸入/輸出進行通訊，因此無需驗證。

支援三種驗證模式。請選擇一種：

模式	使用時機	環境變數
靜態承載權杖	簡單部署、內部服務	`CLICKHOUSE_MCP_AUTH_TOKEN`
OAuth / OIDC（透過 FastMCP）	Azure Entra、Google、GitHub、WorkOS 等	`FASTMCP_SERVER_AUTH=<provider-class-path>`（+ 提供者特定的 `FASTMCP_SERVER_AUTH_*` 變數）
已停用	僅限本機開發	`CLICKHOUSE_MCP_AUTH_DISABLED=true`

若針對 HTTP/SSE 傳輸未設定上述任一項，啟動將會失敗。

設定驗證

產生一個安全權杖（可以是任意隨機字串）：

# Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

使用該權杖設定伺服器：

export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

設定您的 MCP 用戶端，使其在請求中包含該權杖：

針對使用 HTTP/SSE 傳輸的 Claude Desktop：
```
{
  "mcpServers": {
    "mcp-clickhouse": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "Authorization": "Bearer your-generated-token"
      }
    }
  }
}
```
注意：/health 端點刻意無需驗證（請參閱上方的健康檢查端點）。若要驗證承載權杖驗證確實拒絕了未經驗證的請求，請直接存取 MCP 端點本身，例如使用 MCP Inspector，或是在有和沒有 Authorization 標頭的情況下，向 /mcp 發送 POST JSON-RPC 請求，並確認未經驗證的呼叫會回傳 401。

透過 FastMCP 的 OAuth / OIDC

對於使用身分識別提供者（Azure Entra、Google、GitHub、WorkOS 等）的正式環境部署，請將驗證委派給 FastMCP 的內建驗證提供者，而非使用靜態權杖。將 FASTMCP_SERVER_AUTH 設定為 FastMCP 驗證提供者的完整類別路徑，並設定提供者特定的 FASTMCP_SERVER_AUTH_* 變數，同時保持 CLICKHOUSE_MCP_AUTH_TOKEN 未設定。

範例（Azure Entra）：

export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
export FASTMCP_SERVER_AUTH_AZURE_TENANT_ID="<tenant-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID="<client-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET="<client-secret>"

請參閱 FastMCP 文件以取得完整的提供者清單及其所需的環境變數。

開發模式（停用驗證）

僅限本機開發和測試使用，您可以透過以下設定停用驗證：

export CLICKHOUSE_MCP_AUTH_DISABLED=true

警告： 僅在本機開發時使用此設定。當伺服器暴露於任何網路時，請勿停用驗證。

設定

此 MCP 伺服器同時支援 ClickHouse 和 chDB。您可以根據需求啟用其中一個或兩者。

開啟位於以下路徑的 Claude Desktop 設定檔：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%/Claude/claude_desktop_config.json
新增以下內容：

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

更新環境變數以指向您自己的 ClickHouse 服務。

或者，如果您想使用 ClickHouse SQL Playground 進行試用，可以使用以下設定：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "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": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

針對 chDB（嵌入式 ClickHouse 引擎），請新增以下設定：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CHDB_ENABLED": "true",
        "CLICKHOUSE_ENABLED": "false",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

您也可以同時啟用 ClickHouse 和 chDB：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "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": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

找到 uv 的命令條目，並將其替換為 uv 執行檔的絕對路徑。這可確保在啟動伺服器時使用正確的 uv 版本。在 Mac 上，您可以使用 which uv 找到此路徑。
重新啟動 Claude Desktop 以套用變更。

可選的寫入存取權限

預設情況下，此 MCP 強制執行唯讀查詢，以避免在探索過程中發生意外變更。若要允許 DDL 或 INSERT/UPDATE 陳述式，請將 CLICKHOUSE_ALLOW_WRITE_ACCESS 環境變數設為 true。如果 ClickHouse 執行個體本身禁止寫入，伺服器仍會維持唯讀模式。

破壞性操作防護

即使已啟用寫入存取權限 (CLICKHOUSE_ALLOW_WRITE_ACCESS=true)，破壞性操作（DROP TABLE、DROP DATABASE、DROP VIEW、DROP DICTIONARY、TRUNCATE TABLE）仍需要額外的選擇加入旗標以確保安全。這可防止在 AI 探索期間意外刪除資料。

若要啟用破壞性操作，請同時設定兩個旗標：

"env": {
  "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true",
  "CLICKHOUSE_ALLOW_DROP": "true"
}

這種雙層機制確保意外刪除非常困難：

寫入操作（INSERT、UPDATE、CREATE）需要 CLICKHOUSE_ALLOW_WRITE_ACCESS=true
破壞性操作（DROP、TRUNCATE）額外需要 CLICKHOUSE_ALLOW_DROP=true

不使用 uv 執行（使用系統 Python）

如果您偏好使用系統 Python 安裝而非 uv，可以從 PyPI 安裝套件並直接執行：

使用 pip 安裝套件：

python3 -m pip install mcp-clickhouse

若要同時安裝 chDB 支援：

python3 -m pip install 'mcp-clickhouse[chdb]'

若要升級至最新版本：

python3 -m pip install --upgrade mcp-clickhouse

更新您的 Claude Desktop 設定以直接使用 Python：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "python3",
      "args": [
        "-m",
        "mcp_clickhouse.main"
      ],
      "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": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

或者，您可以直接使用已安裝的腳本：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "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": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

注意：如果 Python 執行檔或 mcp-clickhouse 腳本不在您的系統 PATH 中，請務必使用其完整路徑。您可以使用以下指令找到路徑：

which python3 用於 Python 執行檔
which mcp-clickhouse 用於已安裝的腳本

自訂中介軟體

您可以在不修改原始碼的情況下，為 MCP 伺服器新增自訂中介軟體。FastMCP 提供了一個中介軟體系統，允許您攔截和處理 MCP 協定訊息（工具呼叫、資源讀取、提示等）。

如何使用

建立一個 Python 模組，其中包含繼承自 Middleware 的中介軟體類別以及一個 setup_middleware(mcp) 函式：

# my_middleware.py
import logging
from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext

logger = logging.getLogger("my-middleware")

class LoggingMiddleware(Middleware):
    """Log all tool calls."""
    
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'
        logger.info(f"Calling tool: {tool_name}")
        result = await call_next(context)
        logger.info(f"Tool {tool_name} completed")
        return result

def setup_middleware(mcp):
    """Register middleware with the MCP server."""
    mcp.add_middleware(LoggingMiddleware())

將 MCP_MIDDLEWARE_MODULE 環境變數設定為模組名稱（不含 .py 副檔名）：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}

確保您的中介軟體模組位於 Python 的匯入路徑中（例如，與 MCP 伺服器執行時相同的目錄，或作為套件安裝）。

範例中介軟體

example_middleware.py 中提供了一個範例中介軟體模組，展示了常見模式：

記錄所有 MCP 請求
特別記錄工具呼叫
測量請求處理時間

若要使用此範例：

"env": {
  "MCP_MIDDLEWARE_MODULE": "example_middleware"
}

中介軟體功能

Middleware 基礎類別為不同的 MCP 操作提供了掛鉤：

on_message(context, call_next) - 所有訊息都會呼叫
on_request(context, call_next) - 所有請求都會呼叫
on_notification(context, call_next) - 所有通知都會呼叫
on_call_tool(context, call_next) - 執行工具時呼叫
on_read_resource(context, call_next) - 讀取資源時呼叫
on_get_prompt(context, call_next) - 擷取提示時呼叫
on_list_tools(context, call_next) - 列出工具時呼叫
on_list_resources(context, call_next) - 列出資源時呼叫
on_list_resource_templates(context, call_next) - 列出資源範本時呼叫
on_list_prompts(context, call_next) - 列出提示時呼叫

每個掛鉤都會接收一個包含訊息和中繼資料的 MiddlewareContext 物件，以及一個用於繼續管線的 call_next 函式。

透過內容狀態進行動態用戶端設定

中介軟體可以使用 CLIENT_CONFIG_OVERRIDES_KEY 內容狀態鍵，針對每個請求覆寫 ClickHouse 用戶端設定。伺服器會將這些覆寫值與來自環境變數的基礎設定合併。

from fastmcp.server.dependencies import get_context
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY

ctx = get_context()
ctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, {
    "connect_timeout": 60,
    "send_receive_timeout": 120
})

這實現了進階使用案例，例如動態逾時調整、租用戶特定的路由，或每個使用者的連線設定。

開發

在 test-services 目錄中執行 docker compose up -d 以啟動 ClickHouse 叢集。
將以下變數新增至儲存庫根目錄中的 .env 檔案。

注意：在此情境中使用 default 使用者僅限於本機開發目的。

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

執行 uv sync 以安裝相依性。若要安裝 uv，請遵循此處的說明。然後執行 source .venv/bin/activate。
為了方便使用 MCP Inspector 進行測試，請執行 fastmcp dev mcp_clickhouse/mcp_server.py 以啟動 MCP 伺服器。

若要使用 HTTP 傳輸和健康檢查端點進行測試：

# For development, disable authentication
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true python -m mcp_clickhouse.main

# Or with authentication (generate a token first)
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="your-token" python -m mcp_clickhouse.main

# Then in another terminal:
curl http://localhost:8000/health

環境變數

設定分為獨立的群組。將它們混淆是導致難以偵錯的連線失敗的常見原因：

群組	變數	控制
ClickHouse 資料庫連線	`CLICKHOUSE_HOST`、`CLICKHOUSE_PORT`、`CLICKHOUSE_SECURE`、`CLICKHOUSE_VERIFY`、…	此 MCP 伺服器如何透過 HTTP 介面連線至您的 ClickHouse 叢集
MCP 伺服器 / 傳輸	`CLICKHOUSE_MCP_`、`FASTMCP_SERVER_AUTH`、`FASTMCP_SERVER_AUTH_`	MCP 傳輸、驗證和查詢工具執行限制
中介軟體 / chDB	`MCP_MIDDLEWARE_MODULE`、`CHDB_*`	可選擴充功能

[!IMPORTANT] 諸如 CLICKHOUSE_SECURE、CLICKHOUSE_VERIFY 和 CLICKHOUSE_PORT 等變數僅適用於 ClickHouse 資料庫連線。它們不會為 MCP 協定端點設定 TLS、連接埠或驗證。

範例：如果 MCP 伺服器在 Kubernetes 中執行，位於終止 TLS 的入口後方，那是 MCP 傳輸的考量。請保持 CLICKHOUSE_SECURE 與 Pod 存取 ClickHouse 本身的方式一致（HTTPS → true，純 HTTP → false）。若因為 MCP 伺服器位於入口後方而設定 CLICKHOUSE_SECURE=false，將導致伺服器透過 HTTP 撥接 ClickHouse——這通常是針對僅限 HTTPS 的連接埠——並在伺服器日誌中產生不明確的 HTTP/TLS 錯誤。

ClickHouse 資料庫連線

這些變數用於設定 clickhouse-connect HTTP 用戶端，以及基於 ClickHouse 的工具（例如 run_query、list_databases 和 list_tables）的行為。

必要變數

CLICKHOUSE_HOST：您的 ClickHouse 伺服器主機名稱（資料庫端點，而非 MCP 伺服器綁定位址）
CLICKHOUSE_USER：用於 ClickHouse 驗證的使用者名稱
CLICKHOUSE_PASSWORD：用於 ClickHouse 驗證的密碼

[!CAUTION] 請務必將您的 MCP 資料庫使用者視為任何連線到您資料庫的外部用戶端，僅授予其運作所需的最低必要權限。任何時候都應嚴格避免使用預設或管理員使用者。

選用變數

CLICKHOUSE_PORT：您的 ClickHouse 伺服器的 HTTP 介面連接埠
- 預設值：若 CLICKHOUSE_SECURE=true 則為 8443，若 CLICKHOUSE_SECURE=false 則為 8123
- 除非使用非標準連接埠，否則通常無需設定
- 必須是 HTTP 介面連接埠，而非 clickhouse-client 所使用的原生 TCP 協定連接埠
- 常見值：
  - HTTP：8123（明文）/ 8443（TLS）— 本伺服器與 ClickHouse Cloud HTTPS 使用
  - 原生 TCP（此處不支援）：9000（明文）/ 9440（TLS）— clickhouse-client 使用
- 若伺服器回應 Port 9000 is for clickhouse-client program，表示您指向的是原生協定；請切換至 HTTP 連接埠（8123/8443 或您部署環境的 HTTP 對應）
CLICKHOUSE_ROLE：用於驗證的 ClickHouse 角色
- 預設值：無
- 若您的使用者需要特定角色，請設定此項
CLICKHOUSE_SECURE：針對 ClickHouse 資料庫連線啟用 HTTPS（而非針對 MCP 用戶端）
- 預設值："true"
- 僅當 MCP 伺服器透過純 HTTP 連線至 ClickHouse 時（典型的本地 Docker Compose 於連接埠 8123），才設定為 "false"
- 對於 ClickHouse Cloud 和任何 HTTPS 資料庫端點，請保留 "true"——即使 MCP 伺服器本身是透過 HTTP、stdio 或單獨終止 TLS 的入口暴露
- 將此旗標與資料庫連接埠錯誤配對（例如，針對連接埠 8443 使用 CLICKHOUSE_SECURE=false）是常見的設定錯誤，通常會表現為令人困惑的 HTTP 用戶端錯誤，而非明確的「方案錯誤」訊息
CLICKHOUSE_VERIFY：針對 ClickHouse HTTPS 連線啟用/停用 SSL 憑證驗證
- 預設值："true"
- 設定為 "false" 以停用憑證驗證（不建議用於生產環境）
- TLS 憑證：此套件使用您作業系統的信任儲存區，透過 truststore 進行 TLS 憑證驗證。我們在啟動時呼叫 truststore.inject_into_ssl() 以確保正確的憑證處理。僅在發生意外錯誤時，才使用 Python 的預設 SSL 行為作為備用。
CLICKHOUSE_SERVER_HOST_NAME：用於 ClickHouse 連線的 SNI 覆寫和憑證驗證的伺服器主機名稱
- 預設值：無（使用連線主機名稱）
- 當透過代理伺服器或負載平衡器連線，且憑證主機名稱與連線主機名稱不同時，此功能非常有用。設定後，此主機名稱將用於 TLS 交握期間的 SNI（伺服器名稱指示）以及憑證主機名稱驗證。
CLICKHOUSE_PROXY_PATH：ClickHouse HTTP 端點的 URL 路徑前綴
- 預設值：無
- 當 ClickHouse HTTP 介面透過反向代理以路徑前綴暴露時設定此項（例如，/clickhouse）
CLICKHOUSE_CONNECT_TIMEOUT：ClickHouse 用戶端的連線逾時秒數
- 預設值："30"
- 若遇到連線逾時，請增加此值
CLICKHOUSE_SEND_RECEIVE_TIMEOUT：ClickHouse 用戶端的傳送/接收逾時秒數
- 預設值："300"
- 對於長時間執行的查詢，請增加此值
CLICKHOUSE_DATABASE：要使用的預設 ClickHouse 資料庫
- 預設值：無（使用伺服器預設值）
- 設定此項以自動連線到特定資料庫
CLICKHOUSE_ENABLED：啟用/停用 ClickHouse 資料庫工具
- 預設值："true"
- 僅在使用 chDB 時，設定為 "false" 以停用 ClickHouse 工具
CLICKHOUSE_ALLOW_WRITE_ACCESS：允許對 ClickHouse 進行寫入操作（DDL 和 DML）
- 預設值："false"
- 設定為 "true" 以允許 DDL（CREATE、ALTER、DROP）和 DML（INSERT、UPDATE、DELETE）操作
- 停用時（預設），查詢會以 readonly=1 設定執行，以防止資料修改
CLICKHOUSE_ALLOW_DROP：允許破壞性操作（DROP TABLE、DROP DATABASE、DROP VIEW、DROP DICTIONARY、TRUNCATE TABLE）
- 預設值："false"
- 僅在同時設定 CLICKHOUSE_ALLOW_WRITE_ACCESS=true 時生效
- 設定為 "true" 以明確允許破壞性的 DROP 和 TRUNCATE 操作
- 這是一項安全功能，旨在防止 AI 探索期間意外刪除資料

MCP 伺服器與傳輸

這些變數控制 MCP 程序本身，包括傳輸、驗證和查詢工具執行限制。它們獨立於上述的 ClickHouse 資料庫設定。另請參閱 HTTP/SSE 傳輸的驗證。

CLICKHOUSE_MCP_SERVER_TRANSPORT：設定 MCP 伺服器的傳輸方法
- 預設值："stdio"
- 有效選項："stdio"、"http"、"sse"。這對於使用 MCP Inspector 等工具進行本地開發非常有用。
- stdio 是 Claude Desktop 的典型用法；http/sse 會暴露一個網路監聽器（下方的綁定主機/連接埠）
CLICKHOUSE_MCP_BIND_HOST：使用 HTTP 或 SSE 傳輸時，MCP 伺服器綁定的主機
- 預設值："127.0.0.1"
- 設定為 "0.0.0.0" 以綁定到所有網路介面（適用於 Docker 或遠端存取）
- 僅在傳輸為 "http" 或 "sse" 時使用——與 CLICKHOUSE_HOST 無關
CLICKHOUSE_MCP_BIND_PORT：使用 HTTP 或 SSE 傳輸時，MCP 伺服器綁定的連接埠
- 預設值："8000"
- 僅在傳輸為 "http" 或 "sse" 時使用——與 CLICKHOUSE_PORT 無關
CLICKHOUSE_MCP_QUERY_TIMEOUT：查詢工具的逾時秒數
- 預設值："30"
- 若對於大量查詢看到 Query timed out after ... 錯誤，請增加此值
CLICKHOUSE_MCP_AUTH_TOKEN：用於 HTTP/SSE 傳輸的靜態承載權杖
- 預設值：無
- 對於 HTTP/SSE 傳輸，必須設定 CLICKHOUSE_MCP_AUTH_TOKEN、FASTMCP_SERVER_AUTH 或 CLICKHOUSE_MCP_AUTH_DISABLED=true 其中之一
- 使用 uuidgen 或 openssl rand -hex 32 產生
- 用戶端必須在 Authorization: Bearer <token> 標頭中傳送此權杖
FASTMCP_SERVER_AUTH：將驗證委派給 FastMCP 驗證提供者
- 預設值：無
- 值為 AuthProvider 子類別的完整類別路徑，例如 fastmcp.server.auth.providers.azure.AzureProvider 或 fastmcp.server.auth.providers.google.GoogleProvider
- 設定後，FastMCP 會從其自身的 FASTMCP_SERVER_AUTH_* 環境變數自動載入提供者；在此模式下請保持 CLICKHOUSE_MCP_AUTH_TOKEN 未設定
CLICKHOUSE_MCP_AUTH_DISABLED：針對 HTTP/SSE 傳輸停用驗證
- 預設值："false"（已啟用驗證）
- 僅針對本地開發/測試，設定為 "true" 以停用驗證
- **警告：**僅用於本地開發。暴露於網路時請勿停用

中介軟體變數

MCP_MIDDLEWARE_MODULE：包含要注入 MCP 伺服器的自訂中介軟體的 Python 模組名稱
- 預設值：無（未載入中介軟體）
- 設定為您的中介軟體模組的模組名稱（不含 .py 副檔名）
- 該模組必須提供一個 setup_middleware(mcp) 函式
- 詳情與範例請參閱自訂中介軟體

chDB 變數

CHDB_ENABLED：啟用/停用 chDB 功能
- 預設值："false"
- 設定為 "true" 以啟用 chDB 工具
- 需要安裝選用的附加套件：mcp-clickhouse[chdb]
CHDB_DATA_PATH：chDB 資料目錄的路徑
- 預設值：":memory:"（記憶體內資料庫）
- 使用 :memory: 作為記憶體內資料庫
- 使用檔案路徑作為持久性儲存（例如，/path/to/chdb/data）

常見設定陷阱

CLICKHOUSE_SECURE 與 MCP / 入口 TLS — 因為 MCP 伺服器位於 Kubernetes 入口、反向代理之後，或是透過純 HTTP 存取而關閉 CLICKHOUSE_SECURE，並不會停用資料庫 TLS；它只會變更此程序連線至 ClickHouse 的方式。請將入口 TLS 與資料庫用戶端設定分開設定。
原生協定連接埠 — CLICKHOUSE_PORT 必須指向 ClickHouse 的 HTTP 介面（預設為 8123/8443）。連接埠 9000/9440 是用於原生 TCP 協定（clickhouse-client），無法與此伺服器搭配使用。
主機混淆 — CLICKHOUSE_HOST 是資料庫主機名稱。CLICKHOUSE_MCP_BIND_HOST 僅是 MCP HTTP/SSE 伺服器監聽的位址。

設定範例

使用 Docker 進行本地開發：

# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

針對 ClickHouse Cloud：

# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

針對 ClickHouse SQL Playground：

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)

僅使用 chDB（記憶體內）：

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
# CHDB_DATA_PATH defaults to :memory:

使用具備持久性儲存的 chDB：

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
CHDB_DATA_PATH=/path/to/chdb/data

使用 HTTP 傳輸進行 MCP Inspector 或遠端存取：

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
CLICKHOUSE_MCP_BIND_PORT=4200  # Custom port (default: 8000)
CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # One auth mode required for HTTP/SSE (or FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED=true)

使用 HTTP 傳輸進行本地開發（已停用驗證）：

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!

使用 HTTP 傳輸時，伺服器將在設定的連接埠上執行（預設為 8000）。例如，使用上述設定：

MCP 端點：http://localhost:4200/mcp
健康檢查：http://localhost:4200/health

您可以在您的環境中、在 .env 檔案中，或在 Claude Desktop 設定中設定這些變數：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>",
        "CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio",
        "CLICKHOUSE_MCP_BIND_HOST": "127.0.0.1",
        "CLICKHOUSE_MCP_BIND_PORT": "8000"
      }
    }
  }
}

注意：綁定主機和連接埠設定僅在傳輸設定為 "http" 或 "sse" 時使用。

執行測試

uv sync --all-extras --dev # install dev dependencies
uv run ruff check . # run linting

docker compose up -d test_services # start ClickHouse
uv run pytest -v tests
uv run pytest -v tests/test_tool.py # ClickHouse only
CHDB_ENABLED=true uv run --extra chdb pytest -v tests/test_chdb_tool.py # chDB only