ClickHouse MCP 伺服器專案詳細介紹

概述

ClickHouse MCP 伺服器是由 ClickHouse 官方開發的 Model Context Protocol (MCP) 伺服器實現，專門為 AI 助手（如 Claude）提供與 ClickHouse 資料庫的安全連接和互動能力。該專案透過標準化的 MCP 協議，讓 AI 助手能夠執行 SQL 查詢、管理資料庫結構，並進行即時資料分析。

MCP（Model Context Protocol）是一個開放標準，旨在為 AI 應用提供安全、標準化的外部服務整合方式。透過這個伺服器，使用者可以讓 AI 助手直接存取他們的 ClickHouse 資料庫，實現智慧資料查詢和分析。

核心功能

1. SQL 查詢執行 (run_select_query)

• 功能描述: 在 ClickHouse 集群上執行 SQL 查詢
• 安全機制: 所有查詢都在 readonly = 1 模式下執行，確保資料安全
• 輸入參數:
  • sql (字串): 要執行的 SQL 查詢語句
• 使用場景: 資料檢索、統計分析、報表生成

2. 資料庫管理 (list_databases)

• 功能描述: 列出 ClickHouse 集群中的所有資料庫
• 用途: 資料庫結構探索、權限驗證
• 返回內容: 可存取的資料庫列表

3. 表格管理 (list_tables)

• 功能描述: 列出指定資料庫中的所有表格
• 輸入參數:
  • database (字串): 資料庫名稱
• 用途: 表結構探索、資料模型理解

配置與部署

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.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": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

環境變數配置

必需變數

• CLICKHOUSE_HOST: ClickHouse 伺服器主機名
• CLICKHOUSE_USER: 認證使用者名
• CLICKHOUSE_PASSWORD: 認證密碼

可選變數

• CLICKHOUSE_PORT: 埠號
  • 預設: HTTPS 啟用時為 8443，禁用時為 8123
• CLICKHOUSE_SECURE: 啟用/禁用 HTTPS 連接
  • 預設: "true"
• CLICKHOUSE_VERIFY: 啟用/禁用 SSL 憑證驗證
  • 預設: "true"
• CLICKHOUSE_CONNECT_TIMEOUT: 連接逾時時間（秒）
  • 預設: "30"
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: 發送/接收逾時時間（秒）
  • 預設: "300"
• CLICKHOUSE_DATABASE: 預設連接的資料庫
  • 預設: 無（使用伺服器預設）

使用場景

1. ClickHouse SQL 演練場配置

{
  "env": {
    "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
    "CLICKHOUSE_PORT": "8443",
    "CLICKHOUSE_USER": "demo",
    "CLICKHOUSE_PASSWORD": "",
    "CLICKHOUSE_SECURE": "true",
    "CLICKHOUSE_VERIFY": "true"
  }
}

2. 本地開發環境配置

# .env 檔案配置
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_VERIFY=false

3. ClickHouse Cloud 配置

CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
# 使用安全預設設定

開發與測試

環境準備

# 安裝依賴
uv sync

# 激活虛擬環境
source .venv/bin/activate

# 啟動開發伺服器
mcp dev mcp_clickhouse/mcp_server.py

測試流程

# 安裝開發依賴
uv sync --all-extras --dev

# 代碼檢查
uv run ruff check .

# 啟動測試服務
docker compose up -d test_services

# 運行測試
uv run pytest tests

安全考量

資料庫權限管理

• 最小權限原則: MCP 資料庫使用者應只擁有必要的最小權限
• 避免管理員帳戶: 嚴禁使用預設或管理員使用者
• 只讀模式: 所有查詢都在只讀模式下執行，防止資料修改

網路安全

• HTTPS 連接: 生產環境建議啟用 HTTPS
• 憑證驗證: 啟用 SSL 憑證驗證確保連接安全
• 逾時設定: 合理設定連接和查詢逾時，防止資源佔用

技術特性

相容性

• Python 版本: 支援 Python 3.13
• 依賴管理: 使用 uv 進行包管理
• 容器化: 支援 Docker 部署
• 跨平台: 支援 macOS、Windows、Linux

性能優化

• 連接池: 高效的資料庫連接管理
• 逾時控制: 可配置的連接和查詢逾時
• 非同步支援: 支援非同步查詢執行

總結

ClickHouse MCP 伺服器專案為 AI 助手與 ClickHouse 資料庫之間搭建了一座安全、高效的橋樑。透過標準化的 MCP 協議，它讓 AI 助手能夠理解和操作複雜的資料庫結構，執行 sophisticated 的 SQL 查詢，並提供即時的資料洞察。

主要優勢

1. 官方支援: 由 ClickHouse 官方維護，確保相容性和穩定性
2. 安全設計: 內置只讀模式和權限控制，保護資料安全
3. 易於整合: 標準化的 MCP 協議，簡化 AI 應用整合
4. 靈活配置: 支援多種部署場景，從本地開發到雲端生產
5. 開發友好: 完整的開發工具鏈和測試框架

適用場景

• 資料分析: 讓 AI 助手協助進行複雜的資料分析任務
• 商業智慧: 自動化報表生成和資料洞察
• 即時監控: 結合 AI 進行系統和業務指標監控
• 資料探索: 透過自然語言查詢探索資料庫結構和內容

這個專案代表了 AI 與資料庫整合的新方向，為開發者提供了一個強大而安全的工具，讓 AI 助手能夠真正理解和操作企業級資料資源。