ClickHouse

chính thức

Truy vấn máy chủ cơ sở dữ liệu ClickHouse của bạn.

GitHub
839

Bạn có thể làm gì với Click House MCP?

  • Chạy truy vấn SQL chỉ đọc — Yêu cầu trợ lý thực thi bất kỳ truy vấn SELECT nào trên cụm ClickHouse của bạn bằng run_query.
  • Liệt kê cơ sở dữ liệu và bảng — Khám phá lược đồ của bạn bằng cách liệt kê tất cả cơ sở dữ liệu với list_databases hoặc phân trang qua các bảng trong một cơ sở dữ liệu cụ thể với list_tables.
  • Truy vấn tệp và URL trực tiếp qua chDB — Sử dụng run_chdb_select_query để chạy SQL trên các tệp cục bộ hoặc nguồn dữ liệu từ xa mà không cần tải chúng vào ClickHouse trước.
  • Kiểm soát các thao tác ghi và phá hủy — Bật CLICKHOUSE_ALLOW_WRITE_ACCESS cho DDL/DML, và tùy chọn CLICKHOUSE_ALLOW_DROP để cho phép các câu lệnh DROP hoặc TRUNCATE trong các phiên hỗ trợ AI.

Tài liệu

ClickHouse MCP Server

PyPI - Version

Một máy chủ MCP dành cho ClickHouse.

mcp-clickhouse MCP server

Tính năng

Công cụ ClickHouse

  • run_query

    • Thực thi các truy vấn SQL trên cụm ClickHouse của bạn.
    • Đầu vào: query (chuỗi): Truy vấn SQL cần thực thi.
    • Các truy vấn chạy ở chế độ chỉ đọc theo mặc định (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), nhưng có thể bật ghi một cách rõ ràng nếu cần.

  • list_databases

    • Liệt kê tất cả cơ sở dữ liệu trên cụm ClickHouse của bạn.

  • list_tables

    • Liệt kê các bảng trong một cơ sở dữ liệu với phân trang.
    • Đầu vào bắt buộc: database (chuỗi).
    • Đầu vào tùy chọn:
      • like / not_like (chuỗi): Áp dụng bộ lọc LIKE hoặc NOT LIKE cho tên bảng.
      • page_token (chuỗi): Token được trả về từ lần gọi trước để lấy trang tiếp theo.
      • page_size (số nguyên, mặc định 50): Số lượng bảng trả về mỗi trang.
      • include_detailed_columns (boolean, mặc định true): Khi false, bỏ qua siêu dữ liệu cột để phản hồi nhẹ hơn trong khi vẫn giữ đầy đủ create_table_query.
    • Hình dạng phản hồi:
      • tables: Mảng các đối tượng bảng cho trang hiện tại.
      • next_page_token: Truyền lại giá trị này để lấy trang tiếp theo, hoặc null khi không còn bảng nào nữa.
      • total_tables: Tổng số bảng khớp với các bộ lọc được cung cấp.

Công cụ chDB

  • run_chdb_select_query
    • Thực thi các truy vấn SQL bằng công cụ ClickHouse nhúng của chDB.
    • Đầu vào: query (chuỗi): Truy vấn SQL cần thực thi.
    • Truy vấn dữ liệu trực tiếp từ nhiều nguồn khác nhau (tệp, URL, cơ sở dữ liệu) mà không cần quy trình ETL.
    • Yêu cầu phần mở rộng tùy chọn chdb: pip install 'mcp-clickhouse[chdb]'

Điểm cuối Kiểm tra Sức khỏe

Khi chạy với vận chuyển HTTP hoặc SSE, một điểm cuối kiểm tra sức khỏe có sẵn tại /health. Điểm cuối này:

  • Trả về 200 OK (nội dung: OK) nếu máy chủ khỏe mạnh và có thể kết nối đến ClickHouse
  • Trả về 503 Service Unavailable với thông báo lỗi chung nếu máy chủ không thể kết nối đến ClickHouse

Điểm cuối này cố ý không xác thực để các đầu dò điều phối (ví dụ: Kubernetes liveness/readiness, bộ cân bằng tải) có thể truy cập mà không cần thông tin xác thực. Nội dung phản hồi được cố ý tối giản để tránh rò rỉ chuỗi phiên bản backend hoặc chi tiết lỗi; gỡ lỗi lỗi thông qua nhật ký máy chủ.

Ví dụ:

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

Bảo mật

Xác thực cho Vận chuyển HTTP/SSE

Khi sử dụng vận chuyển HTTP hoặc SSE, xác thực là bắt buộc theo mặc định. Vận chuyển stdio (mặc định) không yêu cầu xác thực vì nó chỉ giao tiếp qua đầu vào/đầu ra tiêu chuẩn.

Ba chế độ xác thực được hỗ trợ. Chọn một:

Chế độKhi nào sử dụngBiến môi trường
Token bearer tĩnhTriển khai đơn giản, dịch vụ nội bộCLICKHOUSE_MCP_AUTH_TOKEN
OAuth / OIDC (qua FastMCP)Azure Entra, Google, GitHub, WorkOS, v.v.FASTMCP_SERVER_AUTH=<provider-class-path> (+ các biến FASTMCP_SERVER_AUTH_* cụ thể của nhà cung cấp)
Vô hiệu hóaChỉ phát triển cục bộCLICKHOUSE_MCP_AUTH_DISABLED=true

Khởi động thất bại nếu không có cấu hình nào trong số này được thiết lập cho vận chuyển HTTP/SSE.

Thiết lập Xác thực

  1. Tạo một token an toàn (có thể là bất kỳ chuỗi ngẫu nhiên nào):

    # Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

  2. Cấu hình máy chủ với token:

    export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

  3. Cấu hình máy khách MCP của bạn để bao gồm token trong các yêu cầu:

    Đối với Claude Desktop với vận chuyển HTTP/SSE:

    {
  "mcpServers": {
    "mcp-clickhouse": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "Authorization": "Bearer your-generated-token"
      }
    }
  }
}

    Lưu ý: điểm cuối /health cố ý không xác thực (xem Điểm cuối Kiểm tra Sức khỏe ở trên). Để xác minh rằng xác thực bearer-token thực sự từ chối các yêu cầu không xác thực, hãy truy cập chính điểm cuối MCP, ví dụ: với MCP Inspector, hoặc bằng cách POST một yêu cầu JSON-RPC đến /mcp có và không có tiêu đề Authorization và xác nhận rằng cuộc gọi không xác thực trả về 401.

OAuth / OIDC qua FastMCP

Đối với triển khai sản xuất với các nhà cung cấp danh tính (Azure Entra, Google, GitHub, WorkOS, v.v.), ủy quyền xác thực cho các nhà cung cấp xác thực tích hợp của FastMCP thay vì sử dụng token tĩnh. Đặt FASTMCP_SERVER_AUTH thành đường dẫn lớp đầy đủ của nhà cung cấp xác thực FastMCP, cùng với các biến FASTMCP_SERVER_AUTH_* cụ thể của nhà cung cấp, và để trống CLICKHOUSE_MCP_AUTH_TOKEN.

Ví dụ (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>"

Xem tài liệu FastMCP để biết danh sách đầy đủ các nhà cung cấp và biến môi trường yêu cầu của chúng.

Chế độ Phát triển (Vô hiệu hóa Xác thực)

Chỉ dành cho phát triển và kiểm thử cục bộ, bạn có thể vô hiệu hóa xác thực bằng cách đặt:

export CLICKHOUSE_MCP_AUTH_DISABLED=true

CẢNH BÁO: Chỉ sử dụng điều này cho phát triển cục bộ. Không vô hiệu hóa xác thực khi máy chủ được tiếp xúc với bất kỳ mạng nào.

Cấu hình

Máy chủ MCP này hỗ trợ cả ClickHouse và chDB. Bạn có thể bật một trong hai hoặc cả hai tùy theo nhu cầu.

  1. Mở tệp cấu hình Claude Desktop nằm tại:

    • Trên macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Trên Windows: %APPDATA%/Claude/claude_desktop_config.json

  2. Thêm nội dung sau:

{
  "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"
      }
    }
  }
}

Cập nhật các biến môi trường để trỏ đến dịch vụ ClickHouse của riêng bạn.

Hoặc, nếu bạn muốn dùng thử với ClickHouse SQL Playground, bạn có thể sử dụng cấu hình sau:

{
  "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"
      }
    }
  }
}

Đối với chDB (công cụ ClickHouse nhúng), thêm cấu hình sau:

{
  "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"
      }
    }
  }
}

Bạn cũng có thể bật đồng thời cả ClickHouse và 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"
      }
    }
  }
}

  1. Xác định vị trí mục lệnh cho uv và thay thế nó bằng đường dẫn tuyệt đối đến tệp thực thi uv. Điều này đảm bảo rằng phiên bản chính xác của uv được sử dụng khi khởi động máy chủ. Trên máy mac, bạn có thể tìm đường dẫn này bằng cách sử dụng which uv.

  2. Khởi động lại Claude Desktop để áp dụng các thay đổi.

Quyền Ghi Tùy chọn

Theo mặc định, MCP này thực thi các truy vấn chỉ đọc để các thay đổi ngẫu nhiên không thể xảy ra trong quá trình khám phá. Để cho phép các câu lệnh DDL hoặc INSERT/UPDATE, hãy đặt biến môi trường CLICKHOUSE_ALLOW_WRITE_ACCESS thành true. Máy chủ vẫn thực thi chế độ chỉ đọc nếu chính phiên bản ClickHouse không cho phép ghi.

Bảo vệ Hoạt động Hủy diệt

Ngay cả khi quyền ghi được bật (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), các hoạt động hủy diệt (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) yêu cầu một cờ chấp thuận bổ sung để đảm bảo an toàn. Điều này ngăn chặn việc xóa dữ liệu ngẫu nhiên trong quá trình khám phá AI.

Để bật các hoạt động hủy diệt, hãy đặt cả hai cờ:

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

Cách tiếp cận hai lớp này đảm bảo rằng việc xóa ngẫu nhiên là rất khó xảy ra:

  • Hoạt động ghi (INSERT, UPDATE, CREATE) yêu cầu CLICKHOUSE_ALLOW_WRITE_ACCESS=true
  • Hoạt động hủy diệt (DROP, TRUNCATE) yêu cầu thêm CLICKHOUSE_ALLOW_DROP=true

Chạy Không Cần uv (Sử dụng Python Hệ thống)

Nếu bạn muốn sử dụng cài đặt Python hệ thống thay vì uv, bạn có thể cài đặt gói từ PyPI và chạy trực tiếp:

  1. Cài đặt gói bằng pip:

    python3 -m pip install mcp-clickhouse

    Để cài đặt hỗ trợ chDB:

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

    Để nâng cấp lên phiên bản mới nhất:

    python3 -m pip install --upgrade mcp-clickhouse

  2. Cập nhật cấu hình Claude Desktop của bạn để sử dụng Python trực tiếp:

{
  "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"
      }
    }
  }
}

Ngoài ra, bạn có thể sử dụng tập lệnh đã cài đặt trực tiếp:

{
  "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"
      }
    }
  }
}

Lưu ý: Đảm bảo sử dụng đường dẫn đầy đủ đến tệp thực thi Python hoặc tập lệnh mcp-clickhouse nếu chúng không nằm trong PATH hệ thống của bạn. Bạn có thể tìm đường dẫn bằng cách sử dụng:

  • which python3 cho tệp thực thi Python
  • which mcp-clickhouse cho tập lệnh đã cài đặt

Middleware Tùy chỉnh

Bạn có thể thêm middleware tùy chỉnh vào máy chủ MCP mà không cần sửa đổi mã nguồn. FastMCP cung cấp một hệ thống middleware cho phép bạn chặn và xử lý các thông điệp giao thức MCP (gọi công cụ, đọc tài nguyên, lời nhắc, v.v.).

Cách Sử dụng

  1. Tạo một mô-đun Python với các lớp middleware mở rộng Middleware và một hàm 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())
  1. Đặt biến môi trường MCP_MIDDLEWARE_MODULE thành tên mô-đun (không có phần mở rộng .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"
      }
    }
  }
}
  1. Đảm bảo mô-đun middleware của bạn nằm trong đường dẫn nhập của Python (ví dụ: trong cùng thư mục nơi máy chủ MCP chạy, hoặc được cài đặt dưới dạng gói).

Middleware Ví dụ

Một mô-đun middleware ví dụ được cung cấp trong example_middleware.py hiển thị các mẫu phổ biến:

  • Ghi nhật ký tất cả các yêu cầu MCP
  • Ghi nhật ký cụ thể các lần gọi công cụ
  • Đo thời gian xử lý yêu cầu

Để sử dụng ví dụ:

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

Khả năng Middleware

Lớp cơ sở Middleware cung cấp các hook cho các hoạt động MCP khác nhau:

  • on_message(context, call_next) - Được gọi cho tất cả các thông điệp
  • on_request(context, call_next) - Được gọi cho tất cả các yêu cầu
  • on_notification(context, call_next) - Được gọi cho tất cả các thông báo
  • on_call_tool(context, call_next) - Được gọi khi một công cụ được thực thi
  • on_read_resource(context, call_next) - Được gọi khi một tài nguyên được đọc
  • on_get_prompt(context, call_next) - Được gọi khi một lời nhắc được truy xuất
  • on_list_tools(context, call_next) - Được gọi khi liệt kê công cụ
  • on_list_resources(context, call_next) - Được gọi khi liệt kê tài nguyên
  • on_list_resource_templates(context, call_next) - Được gọi khi liệt kê mẫu tài nguyên
  • on_list_prompts(context, call_next) - Được gọi khi liệt kê lời nhắc

Mỗi hook nhận một đối tượng MiddlewareContext chứa thông điệp và siêu dữ liệu, và một hàm call_next để tiếp tục đường ống.

Cấu hình Máy khách Động qua Trạng thái Ngữ cảnh

Middleware có thể ghi đè cấu hình máy khách ClickHouse trên cơ sở từng yêu cầu bằng cách sử dụng khóa trạng thái ngữ cảnh CLIENT_CONFIG_OVERRIDES_KEY. Máy chủ hợp nhất các ghi đè này với cấu hình cơ sở từ các biến môi trường.

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
})

Điều này cho phép các trường hợp sử dụng nâng cao như điều chỉnh thời gian chờ động, định tuyến theo đối tượng thuê, hoặc cài đặt kết nối cho từng người dùng.

Phát triển

  1. Trong thư mục test-services chạy docker compose up -d để khởi động cụm ClickHouse.

  2. Thêm các biến sau vào tệp .env trong thư mục gốc của kho lưu trữ.

Lưu ý: Việc sử dụng người dùng default trong ngữ cảnh này chỉ dành cho mục đích phát triển cục bộ.

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

  1. Chạy uv sync để cài đặt các phụ thuộc. Để cài đặt uv làm theo hướng dẫn tại đây. Sau đó thực hiện source .venv/bin/activate.

  2. Để kiểm tra dễ dàng với MCP Inspector, chạy fastmcp dev mcp_clickhouse/mcp_server.py để khởi động máy chủ MCP.

  3. Để kiểm tra với vận chuyển HTTP và điểm cuối kiểm tra sức khỏe:

    # 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

Biến Môi trường

Cấu hình được chia thành các nhóm độc lập. Việc trộn lẫn chúng là nguyên nhân phổ biến gây ra lỗi kết nối khó gỡ lỗi:

NhómBiếnKiểm soát
Kết nối cơ sở dữ liệu ClickHouseCLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, …Cách máy chủ MCP này kết nối đến cụm ClickHouse của bạn qua giao diện HTTP
Máy chủ MCP / vận chuyểnCLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*Vận chuyển MCP, xác thực và giới hạn thực thi công cụ truy vấn
Middleware / chDBMCP_MIDDLEWARE_MODULE, CHDB_*Các tiện ích mở rộng tùy chọn

[!QUAN TRỌNG] Các biến như CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY và CLICKHOUSE_PORT chỉ áp dụng cho kết nối cơ sở dữ liệu ClickHouse. Chúng không cấu hình TLS, cổng hoặc xác thực cho điểm cuối giao thức MCP.

Ví dụ: nếu máy chủ MCP chạy trong Kubernetes phía sau một ingress kết thúc TLS, đó là mối quan tâm của vận chuyển MCP. Giữ CLICKHOUSE_SECURE phù hợp với cách pod tiếp cận chính ClickHouse (HTTPS → true, HTTP thường → false). Đặt CLICKHOUSE_SECURE=false vì máy chủ MCP nằm sau một ingress sẽ khiến máy chủ quay số ClickHouse qua HTTP—thường là trên một cổng chỉ dành cho HTTPS—và tạo ra lỗi HTTP/TLS không rõ ràng trong nhật ký máy chủ.

Kết nối cơ sở dữ liệu ClickHouse

Các biến này cấu hình ứng dụng HTTP clickhouse-connect và hành vi của các công cụ được ClickHouse hỗ trợ như run_query, list_databases và list_tables.

Biến bắt buộc
  • CLICKHOUSE_HOST: Tên máy chủ của máy chủ ClickHouse của bạn (điểm cuối cơ sở dữ liệu, không phải địa chỉ liên kết máy chủ MCP)
  • CLICKHOUSE_USER: Tên người dùng để xác thực ClickHouse
  • CLICKHOUSE_PASSWORD: Mật khẩu để xác thực ClickHouse

[!CAUTION] Điều quan trọng là phải đối xử với người dùng cơ sở dữ liệu MCP của bạn như bất kỳ ứng dụng khách bên ngoài nào kết nối với cơ sở dữ liệu của bạn, chỉ cấp các đặc quyền tối thiểu cần thiết cho hoạt động của nó. Tuyệt đối tránh sử dụng người dùng mặc định hoặc quản trị viên.

Biến tùy chọn
  • CLICKHOUSE_PORT: Cổng giao diện HTTP của máy chủ ClickHouse của bạn
    • Mặc định: 8443 nếu CLICKHOUSE_SECURE=true, 8123 nếu CLICKHOUSE_SECURE=false
    • Thường không cần đặt trừ khi sử dụng cổng không chuẩn
    • Phải là cổng giao diện HTTP, không phải cổng giao thức TCP gốc được sử dụng bởi clickhouse-client
    • Các giá trị phổ biến:
      • HTTP: 8123 (thường) / 8443 (TLS) — được máy chủ này và ClickHouse Cloud HTTPS sử dụng
      • TCP gốc (không được hỗ trợ ở đây): 9000 (thường) / 9440 (TLS) — được clickhouse-client sử dụng
    • Nếu máy chủ phản hồi với Port 9000 is for clickhouse-client program, bạn đang trỏ đến giao thức gốc; hãy chuyển sang cổng HTTP (8123/8443 hoặc ánh xạ HTTP của triển khai của bạn)
  • CLICKHOUSE_ROLE: Vai trò ClickHouse để sử dụng cho xác thực
    • Mặc định: Không có
    • Đặt biến này nếu người dùng của bạn yêu cầu một vai trò cụ thể
  • CLICKHOUSE_SECURE: Bật HTTPS cho kết nối cơ sở dữ liệu ClickHouse (không dành cho ứng dụng khách MCP)
    • Mặc định: "true"
    • Chỉ đặt thành "false" khi máy chủ MCP truy cập ClickHouse qua HTTP thường (điển hình cho Docker Compose cục bộ trên cổng 8123)
    • Để "true" cho ClickHouse Cloud và bất kỳ điểm cuối cơ sở dữ liệu HTTPS nào—ngay cả khi bản thân máy chủ MCP được hiển thị qua HTTP, stdio hoặc một ingress kết thúc TLS riêng biệt
    • Không khớp cờ này với cổng cơ sở dữ liệu (ví dụ: CLICKHOUSE_SECURE=false với cổng 8443) là một lỗi thiết lập thường gặp và thường biểu hiện dưới dạng lỗi ứng dụng khách HTTP khó hiểu thay vì thông báo "sai lược đồ" rõ ràng
  • CLICKHOUSE_VERIFY: Bật/tắt xác minh chứng chỉ SSL cho kết nối HTTPS ClickHouse
    • Mặc định: "true"
    • Đặt thành "false" để tắt xác minh chứng chỉ (không khuyến nghị cho môi trường production)
    • Chứng chỉ TLS: Gói sử dụng kho lưu trữ tin cậy của hệ điều hành của bạn để xác minh chứng chỉ TLS thông qua truststore. Chúng tôi gọi truststore.inject_into_ssl() khi khởi động để đảm bảo xử lý chứng chỉ đúng cách. Hành vi SSL mặc định của Python chỉ được sử dụng như một phương án dự phòng nếu xảy ra lỗi không mong muốn.
  • CLICKHOUSE_SERVER_HOST_NAME: Tên máy chủ cho ghi đè SNI và xác thực chứng chỉ trên kết nối ClickHouse
    • Mặc định: Không có (sử dụng tên máy chủ kết nối)
    • Điều này hữu ích khi kết nối thông qua proxy hoặc bộ cân bằng tải nơi tên máy chủ chứng chỉ khác với tên máy chủ kết nối. Khi được đặt, tên máy chủ này sẽ được sử dụng cho cả SNI (Chỉ dẫn Tên Máy chủ) trong quá trình bắt tay TLS và để xác thực tên máy chủ chứng chỉ.
  • CLICKHOUSE_PROXY_PATH: Tiền tố đường dẫn URL cho điểm cuối HTTP ClickHouse
    • Mặc định: Không có
    • Đặt biến này khi giao diện HTTP ClickHouse được hiển thị phía sau một proxy ngược dưới một tiền tố đường dẫn (ví dụ: /clickhouse)
  • CLICKHOUSE_CONNECT_TIMEOUT: Thời gian chờ kết nối tính bằng giây cho ứng dụng khách ClickHouse
    • Mặc định: "30"
    • Tăng giá trị này nếu bạn gặp phải tình trạng hết thời gian chờ kết nối
  • CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Thời gian chờ gửi/nhận tính bằng giây cho ứng dụng khách ClickHouse
    • Mặc định: "300"
    • Tăng giá trị này cho các truy vấn chạy lâu
  • CLICKHOUSE_DATABASE: Cơ sở dữ liệu ClickHouse mặc định để sử dụng
    • Mặc định: Không có (sử dụng mặc định của máy chủ)
    • Đặt biến này để tự động kết nối với một cơ sở dữ liệu cụ thể
  • CLICKHOUSE_ENABLED: Bật/tắt các công cụ cơ sở dữ liệu ClickHouse
    • Mặc định: "true"
    • Đặt thành "false" để tắt các công cụ ClickHouse khi chỉ sử dụng chDB
  • CLICKHOUSE_ALLOW_WRITE_ACCESS: Cho phép các thao tác ghi (DDL và DML) đối với ClickHouse
    • Mặc định: "false"
    • Đặt thành "true" để cho phép các thao tác DDL (CREATE, ALTER, DROP) và DML (INSERT, UPDATE, DELETE)
    • Khi bị tắt (mặc định), các truy vấn chạy với cài đặt readonly=1 để ngăn chặn sửa đổi dữ liệu
  • CLICKHOUSE_ALLOW_DROP: Cho phép các thao tác hủy (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE)
    • Mặc định: "false"
    • Chỉ có hiệu lực khi CLICKHOUSE_ALLOW_WRITE_ACCESS=true cũng được đặt
    • Đặt thành "true" để cho phép rõ ràng các thao tác DROP và TRUNCATE hủy diệt
    • Đây là một tính năng an toàn để ngăn chặn việc vô tình xóa dữ liệu trong quá trình khám phá AI

Máy chủ MCP và truyền tải

Các biến này kiểm soát chính tiến trình MCP, bao gồm truyền tải, xác thực và giới hạn thực thi công cụ truy vấn. Chúng độc lập với các cài đặt cơ sở dữ liệu ClickHouse ở trên. Xem thêm Xác thực cho Truyền tải HTTP/SSE.

  • CLICKHOUSE_MCP_SERVER_TRANSPORT: Đặt phương thức truyền tải cho máy chủ MCP
    • Mặc định: "stdio"
    • Các tùy chọn hợp lệ: "stdio", "http", "sse". Điều này hữu ích cho phát triển cục bộ với các công cụ như MCP Inspector.
    • stdio là điển hình cho Claude Desktop; http/sse hiển thị một trình nghe mạng (máy chủ/cổng liên kết bên dưới)
  • CLICKHOUSE_MCP_BIND_HOST: Máy chủ để liên kết máy chủ MCP khi sử dụng truyền tải HTTP hoặc SSE
    • Mặc định: "127.0.0.1"
    • Đặt thành "0.0.0.0" để liên kết với tất cả các giao diện mạng (hữu ích cho Docker hoặc truy cập từ xa)
    • Chỉ được sử dụng khi truyền tải là "http" hoặc "sse" — không liên quan đến CLICKHOUSE_HOST
  • CLICKHOUSE_MCP_BIND_PORT: Cổng để liên kết máy chủ MCP khi sử dụng truyền tải HTTP hoặc SSE
    • Mặc định: "8000"
    • Chỉ được sử dụng khi truyền tải là "http" hoặc "sse" — không liên quan đến CLICKHOUSE_PORT
  • CLICKHOUSE_MCP_QUERY_TIMEOUT: Thời gian chờ tính bằng giây cho các công cụ truy vấn
    • Mặc định: "30"
    • Tăng giá trị này nếu bạn thấy lỗi Query timed out after ... cho các truy vấn nặng
  • CLICKHOUSE_MCP_AUTH_TOKEN: Token bearer tĩnh cho truyền tải HTTP/SSE
    • Mặc định: Không có
    • Một trong CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH hoặc CLICKHOUSE_MCP_AUTH_DISABLED=true là bắt buộc cho truyền tải HTTP/SSE
    • Tạo bằng cách sử dụng uuidgen hoặc openssl rand -hex 32
    • Ứng dụng khách phải gửi token này trong tiêu đề Authorization: Bearer <token>
  • FASTMCP_SERVER_AUTH: Ủy quyền xác thực cho một nhà cung cấp xác thực FastMCP
    • Mặc định: Không có
    • Giá trị là đường dẫn lớp đầy đủ của một lớp con AuthProvider, ví dụ: fastmcp.server.auth.providers.azure.AzureProvider hoặc fastmcp.server.auth.providers.google.GoogleProvider
    • Khi được đặt, FastMCP tự động tải nhà cung cấp từ các biến môi trường FASTMCP_SERVER_AUTH_* của chính nó; để trống CLICKHOUSE_MCP_AUTH_TOKEN trong chế độ này
  • CLICKHOUSE_MCP_AUTH_DISABLED: Tắt xác thực cho truyền tải HTTP/SSE
    • Mặc định: "false" (xác thực được bật)
    • Đặt thành "true" để tắt xác thực chỉ cho phát triển/kiểm thử cục bộ
    • CẢNH BÁO: Chỉ sử dụng cho phát triển cục bộ. Không tắt khi tiếp xúc với mạng

Biến Middleware

  • MCP_MIDDLEWARE_MODULE: Tên mô-đun Python chứa middleware tùy chỉnh để đưa vào máy chủ MCP
    • Mặc định: Không có (không tải middleware)
    • Đặt thành tên mô-đun (không có phần mở rộng .py) của mô-đun middleware của bạn
    • Mô-đun phải cung cấp một hàm setup_middleware(mcp)
    • Xem Middleware Tùy chỉnh để biết chi tiết và ví dụ

Biến chDB

  • CHDB_ENABLED: Bật/tắt chức năng chDB
    • Mặc định: "false"
    • Đặt thành "true" để bật các công cụ chDB
    • Yêu cầu cài đặt phần bổ sung tùy chọn: mcp-clickhouse[chdb]
  • CHDB_DATA_PATH: Đường dẫn đến thư mục dữ liệu chDB
    • Mặc định: ":memory:" (cơ sở dữ liệu trong bộ nhớ)
    • Sử dụng :memory: cho cơ sở dữ liệu trong bộ nhớ
    • Sử dụng đường dẫn tệp cho lưu trữ liên tục (ví dụ: /path/to/chdb/data)

Các lỗi cấu hình phổ biến

  • CLICKHOUSE_SECURE so với MCP / ingress TLS — Việc tắt CLICKHOUSE_SECURE vì máy chủ MCP nằm sau ingress Kubernetes, proxy ngược hoặc được truy cập qua HTTP thường không tắt TLS cơ sở dữ liệu; nó chỉ thay đổi cách tiến trình này kết nối với ClickHouse. Cấu hình ingress TLS tách biệt với cài đặt ứng dụng khách cơ sở dữ liệu.
  • Cổng giao thức gốc — CLICKHOUSE_PORT phải nhắm mục tiêu giao diện HTTP của ClickHouse (8123/8443 theo mặc định). Các cổng 9000/9440 dành cho giao thức TCP gốc (clickhouse-client) và sẽ không hoạt động với máy chủ này.
  • Nhầm lẫn máy chủ — CLICKHOUSE_HOST là tên máy chủ cơ sở dữ liệu. CLICKHOUSE_MCP_BIND_HOST chỉ là địa chỉ mà máy chủ MCP HTTP/SSE lắng nghe.

Cấu hình Ví dụ

Để phát triển cục bộ với 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

Cho 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

Cho ClickHouse SQL Playground:

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

Chỉ dành cho chDB (trong bộ nhớ):

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

Cho chDB với lưu trữ liên tục:

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

Cho MCP Inspector hoặc truy cập từ xa với truyền tải HTTP:

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)

Để phát triển cục bộ với truyền tải HTTP (xác thực bị tắt):

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

Khi sử dụng truyền tải HTTP, máy chủ sẽ chạy trên cổng đã cấu hình (mặc định 8000). Ví dụ: với cấu hình trên:

  • Điểm cuối MCP: http://localhost:4200/mcp
  • Kiểm tra sức khỏe: http://localhost:4200/health

Bạn có thể đặt các biến này trong môi trường của mình, trong tệp .env hoặc trong cấu hình 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"
      }
    }
  }
}

Lưu ý: Cài đặt máy chủ và cổng liên kết chỉ được sử dụng khi truyền tải được đặt thành "http" hoặc "sse".

Chạy kiểm thử

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

Tổng quan YouTube

YouTube