ClickHouse

chính thức

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

GitHub
899

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

  • Chạy truy vấn SQL — Yêu cầu thực thi bất kỳ truy vấn SQL nào trên cụm ClickHouse của bạn qua run_query, với các tham số có tên tùy chọn thông qua params.
  • Liệt kê cơ sở dữ liệu — Khám phá tất cả các cơ sở dữ liệu có sẵn trên cụm ClickHouse của bạn bằng list_databases.
  • Duyệt bảng với bộ lọc — Sử dụng list_tables để khám phá các bảng trong cơ sở dữ liệu, áp dụng các mẫu like/not_like và phân trang qua page_token và page_size.
  • Kiểm tra lược đồ truy vấn — Yêu cầu DESCRIBE (<query>) hoặc EXPLAIN ESTIMATE <query> qua run_query để kiểm tra các cột đầu ra hoặc ước tính số lần đọc trước khi thực thi.
  • Truy vấn dữ liệu chDB nhúng — Chạy SQL trực tiếp trên công cụ nhúng của chDB để truy vấn tệp, URL hoặc cơ sở dữ liệu mà không cần ETL, sử dụng run_chdb_select_query.

Tài liệu

Máy chủ MCP ClickHouse

PyPI - Version

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

mcp-clickhouse MCP server

Máy chủ triển khai MCP 2026-07-28 và hỗ trợ bắt tay khởi tạo legacy từ 2024-11-05 đến 2025-11-25. Các máy khách hiện đại sử dụng yêu cầu không phiên và server/discover. Các máy khách hiện có có thể tiếp tục đàm phán giao thức legacy.

[!NOTE] Các yêu cầu HTTP không có MCP-Protocol-Version được định tuyến qua xử lý legacy để các máy khách từ trước 2025-06-18 có thể tiếp tục kết nối. MCP 2026-07-28 cho phép hành vi này trên các máy chủ hỗ trợ các máy khách đó. Các máy khách hiện đại nên gửi tiêu đề trong mọi yêu cầu POST.

Tính năng

Công cụ ClickHouse

Phản hồi của công cụ ClickHouse là các chuỗi mã hóa JSON. Các số nguyên nằm ngoài [-9007199254740991, 9007199254740991] được trả về dưới dạng chuỗi thập phân để giữ nguyên giá trị chính xác trong các máy khách JavaScript. Điều này áp dụng cho các hàng truy vấn và siêu dữ liệu bảng số nguyên. Các số nguyên trong phạm vi an toàn và giá trị boolean giữ nguyên kiểu JSON của chúng.

  • run_query

    • Thực thi 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.
    • Đầu vào tùy chọn: params (đối tượng): Các giá trị có tên cho các trình giữ chỗ {name:Type} của ClickHouse. Xem Tham số truy vấn.
    • 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 tường minh nếu cần.
    • DESCRIBE (<query>) và EXPLAIN ESTIMATE <query> cũng chạy ở đây và là các cách tùy chọn để kiểm tra lược đồ kết quả của truy vấn hoặc số lần đọc ước tính của nó. Xem Kiểm tra truy vấn trước khi chạy.

  • 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 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): Mã thông báo dùng một lần được trả về từ lệnh gọi trước. Mã này được giữ tối đa một giờ.
      • page_size (int, mặc định 50): Số bảng được trả về mỗi trang; phải lớn hơn 0.
      • include_detailed_columns (bool, mặc định true): Khi false, bỏ qua siêu dữ liệu cột để có 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 giá trị dùng một lần này trước khi hết hạn để lấy trang tiếp theo, hoặc null khi không còn bảng nào.
      • total_tables: Tổng số bảng khớp với các bộ lọc được cung cấp.

Khám phá lược đồ Agents

Các hướng dẫn của máy chủ đề xuất đọc Agents Schema's canonical AGENTS.ROOT qua run_query khi list_databases tiết lộ một cơ sở dữ liệu AGENTS, trước khi viết SQL phân tích. Đây là hướng dẫn cho agent: không có siêu dữ liệu nào được tìm nạp tự động, kết quả công cụ không thay đổi và các quyền ClickHouse hiện có vẫn được áp dụng. Nếu AGENTS.ROOT bị thiếu hoặc không thể truy cập, việc khám phá và truy vấn thông thường vẫn khả dụng.

Tham số truy vấn

Truyền các giá trị riêng biệt với SQL qua đối tượng params tùy chọn:

{
  "query": "SELECT {id:UInt32} AS id, {name:String} AS name",
  "params": {"id": 13, "name": "O'Reilly"}
}

Sử dụng các trình giữ chỗ {name:Type} của ClickHouse mà không cần đặt trong dấu ngoặc kép. Giữ dấu ngoặc nhọn mở, tên và dấu hai chấm liền kề, như trong {id:UInt32}. Khoảng trắng sau dấu hai chấm và trong kiểu được hỗ trợ, như trong {id: UInt32} và {amount:Decimal(18, 4)}. Để tương thích với các phiên bản trình điều khiển được hỗ trợ, hãy bắt đầu tên bằng chữ cái hoặc dấu gạch dưới và chỉ sử dụng chữ cái, chữ số và dấu gạch dưới. Định dạng kiểu Python %s hoặc %(name)s và tham số nhị phân thô $name$ của trình điều khiển không được hỗ trợ. Các lệnh gọi chỉ có query vẫn hoạt động. Bỏ qua params, truyền null hoặc truyền một đối tượng trống sẽ để truy vấn không được ràng buộc.

Các giá trị tham số có thể là chuỗi JSON, số, boolean, null hoặc mảng, miễn là chúng khớp với kiểu ClickHouse đã khai báo:

  • Sử dụng null với kiểu Nullable(...).
  • Truyền các số nguyên chính xác ngoài phạm vi an toàn của JavaScript dưới dạng chuỗi thập phân, ví dụ "18446744073709551615" với {id:UInt64}. Ngày, dấu thời gian và số thập phân chính xác cũng có thể được truyền dưới dạng chuỗi với kiểu ClickHouse tương ứng.
  • Ràng buộc vectơ dưới dạng một mảng, ví dụ {vector:Array(Float32)} với "params": {"vector": [0.25, 0.5, 0.75]}.
  • Null bên trong mảng phụ thuộc vào trình điều khiển đã cài đặt. Chúng hoạt động với clickhouse-connect 1.8.0 nhưng không hoạt động với phiên bản tối thiểu được hỗ trợ 1.0.0.
  • Danh sách và đối tượng JSON không thể ràng buộc với các kiểu Tuple và Map của ClickHouse.

Các giá trị bị thiếu và kiểu không tương thích trả về lỗi truy vấn. Với params không trống, một truy vấn mang nhiều điểm bắt đầu trình giữ chỗ {name: chưa kết thúc sẽ bị từ chối, bao gồm cả văn bản giống trình giữ chỗ trong chú thích hoặc chuỗi ký tự. Các truy vấn có tham số sử dụng cùng bảo vệ ghi, thời gian chờ, hủy bỏ và mã hóa kết quả JSON như các truy vấn khác.

Các giá trị tham số nằm ngoài các thông báo nhật ký SQL thông thường của máy chủ MCP, nhưng vẫn nằm trong các đối số công cụ MCP và có thể xuất hiện trong lỗi phụ trợ. ClickHouse 26.3.20.7 thay thế các giá trị vào văn bản truy vấn trong system.query_log, system.processes, và system.text_log. Ràng buộc tham số không phải là tính năng bảo mật và không giảm số lượng giá trị vectơ được gửi trong một lệnh gọi công cụ.

Kiểm tra truy vấn trước khi chạy

run_query cũng chạy DESCRIBE và EXPLAIN ESTIMATE. Cả hai đều là kiểm tra tùy chọn: sử dụng DESCRIBE khi bạn cần các cột và kiểu đầu ra của truy vấn, và sử dụng EXPLAIN ESTIMATE trước một SELECT có thể tốn kém.

DESCRIBE (<query>) kiểm tra lược đồ kết quả và trả về cùng siêu dữ liệu cột đầu ra như DESCRIBE TABLE:

DESCRIBE (SELECT user, sum(amt) FROM events WHERE ts > now() - INTERVAL 30 DAY GROUP BY user)

user      String
sum(amt)  Decimal(38, 2)

ClickHouse phải phân tích truy vấn để trả lời, vì vậy lỗi phân tích xuất hiện ở đây, với thông báo của chính ClickHouse, thay vì giữa chừng khi thực thi:

DESCRIBE (SELECT usr FROM events)  -> Code: 47. Unknown expression identifier `usr` ... Maybe you meant: ['user']
DESCRIBE (SELECT * FROM nosuch)    -> Code: 60. Unknown table expression identifier 'nosuch'

Một truy vấn mô tả sạch sẽ vẫn có thể thất bại khi chạy, do giới hạn bộ nhớ hoặc lỗi máy chủ từ xa, và nó không nói gì về chi phí.

EXPLAIN ESTIMATE <query> trả về các phần, hàng và dấu mà truy vấn sẽ đọc, một hàng cho mỗi bảng, điều này phân biệt tra cứu khóa chính với quét toàn bộ:

EXPLAIN ESTIMATE SELECT count() FROM events WHERE id = 42

database  table   parts  rows   marks
default   events  1      8192   1

Đó là các lần đọc ước tính từ các bảng họ MergeTree, sau khi cắt tỉa khóa chính và phân vùng. Chúng không phải là thời gian chạy và không phải là kích thước kết quả, và các công cụ bảng khác không được bao phủ.

Không câu lệnh nào chạy phần thân truy vấn, nhưng phân tích không phải lúc nào cũng miễn phí: DESCRIBE (SELECT (SELECT sleep(1))) thực thi truy vấn con vô hướng trong khi phân tích. Cả hai đều chỉ đọc và hoạt động dưới CLICKHOUSE_ALLOW_WRITE_ACCESS=false mặc định. Xem tài liệu ClickHouse cho EXPLAIN ESTIMATE và DESCRIBE.

Công cụ chDB

  • run_chdb_select_query
    • Thực thi 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.
    • Các số nguyên ngoài [-9007199254740991, 9007199254740991] được trả về dưới dạng chuỗi thập phân.
    • 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 gói bổ sung 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 truyền tải 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 với 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 với ClickHouse
  • Trả về 503 nếu một lần dò ClickHouse không hoàn thành trong vòng hai giây. Các yêu cầu đồng thời chia sẻ một lần dò đang chạy
  • Tái sử dụng kết quả dò đã hoàn thành trong một giây, vì vậy các lần dò đến liên tiếp không mỗi lần kết nối với ClickHouse. Do đó, một lỗi hoặc phục hồi có thể được báo cáo muộn tối đa một giây

Các yêu cầu GET và HEAD đến điểm cuối cố ý không xác thực và được miễn xác thực Host và Origin để các lần dò của bộ điều phối (ví dụ: Kubernetes liveness/readiness, bộ cân bằng tải) có thể sử dụng IP pod hoặc IP mục tiêu được gán trong thời gian chạy mà không cần cấu hình thêm. /health được dành riêng và không thể được sử dụng làm đường dẫn truyền tải MCP. Nội dung phản hồi cố ý tối thiểu để tránh rò rỉ chuỗi phiên bản phụ trợ hoặc chi tiết lỗi; gỡ lỗi lỗi 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 truyền tải HTTP/SSE

Khi sử dụng truyền tải HTTP hoặc SSE, xác thực bắt buộc theo mặc định. Truyền tải 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
Mã thông báo 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> (+ biến FASTMCP_SERVER_AUTH_* dành riêng cho nhà cung cấp)
Đã tắtChỉ phát triển cục bộCLICKHOUSE_MCP_AUTH_DISABLED=true

Khởi động thất bại nếu không có chế độ nào trong số này được cấu hình cho truyền tải HTTP/SSE.

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

  1. Tạo một mã thông báo 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 mã thông báo:

    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 mã thông báo trong các yêu cầu:

    Đối với Claude Desktop với truyền tải 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 lệnh gọi không xác thực trả về 401.

OAuth / OIDC qua FastMCP

Đối với các triển khai sản xuất với nhà cung cấp danh tính (Azure Entra, Google, GitHub, WorkOS, v.v.), hãy ủ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 mã thông báo tĩnh. Đặt FASTMCP_SERVER_AUTH thành đường dẫn lớp đầy đủ của một nhà cung cấp xác thực FastMCP, cùng với các biến FASTMCP_SERVER_AUTH_* dành riêng cho nhà cung cấp và để CLICKHOUSE_MCP_AUTH_TOKEN không được đặt.

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>"
export FASTMCP_SERVER_AUTH_AZURE_BASE_URL="https://mcp.example.com"
export FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES="read access_as_user"

mcp-clickhouse giữ lại các tiền tố môi trường FastMCP 2.14.7 này cho các nhà cung cấp tích hợp FastMCP 4.0.0:

Đường dẫn lớp nhà cung cấpTiền tố biến nhà cung cấp
fastmcp.server.auth.providers.auth0.Auth0ProviderFASTMCP_SERVER_AUTH_AUTH0_
fastmcp.server.auth.providers.aws.AWSCognitoProviderFASTMCP_SERVER_AUTH_AWS_COGNITO_
fastmcp.server.auth.providers.azure.AzureProviderFASTMCP_SERVER_AUTH_AZURE_
fastmcp.server.auth.providers.descope.DescopeProviderFASTMCP_SERVER_AUTH_DESCOPEPROVIDER_
fastmcp.server.auth.providers.discord.DiscordProviderFASTMCP_SERVER_AUTH_DISCORD_
fastmcp.server.auth.providers.github.GitHubProviderFASTMCP_SERVER_AUTH_GITHUB_
fastmcp.server.auth.providers.google.GoogleProviderFASTMCP_SERVER_AUTH_GOOGLE_
fastmcp.server.auth.providers.introspection.IntrospectionTokenVerifierFASTMCP_SERVER_AUTH_INTROSPECTION_
fastmcp.server.auth.providers.jwt.JWTVerifierFASTMCP_SERVER_AUTH_JWT_
fastmcp.server.auth.providers.oci.OCIProviderFASTMCP_SERVER_AUTH_OCI_
fastmcp.server.auth.providers.scalekit.ScalekitProviderFASTMCP_SERVER_AUTH_SCALEKITPROVIDER_
fastmcp.server.auth.providers.supabase.SupabaseProviderFASTMCP_SERVER_AUTH_SUPABASE_
fastmcp.server.auth.providers.workos.WorkOSProviderFASTMCP_SERVER_AUTH_WORKOS_
fastmcp.server.auth.providers.workos.AuthKitProviderFASTMCP_SERVER_AUTH_AUTHKITPROVIDER_

Thêm tên trường nhà cung cấp viết hoa vào tiền tố. Xem tài liệu FastMCP cho các yêu cầu cấu hình của từng nhà cung cấp.

Các giá trị xác thực được đặt trực tiếp trong môi trường tiến trình có mức ưu tiên cao hơn, không phân biệt chữ hoa chữ thường. Việc tải .env mặc định bắt đầu từ thư mục gói mcp_clickhouse đã cài đặt, giải quyết các liên kết tượng trưng trước tiên và đi lên đến gốc hệ thống tệp. Nó tải tệp .env đầu tiên tìm thấy và không tải gì nếu không có tệp nào. Nó không bao giờ đọc thư mục làm việc, bất kể máy chủ được khởi chạy như thế nào. Một bản kiểm tra mã nguồn thường tìm thấy .env tại gốc kho lưu trữ. Tệp đó cũng có thể cung cấp FASTMCP_SERVER_AUTH và các trường nhà cung cấp của nó. Các giá trị của nó có mức ưu tiên cao hơn tệp xác thực tường minh hoặc tương thích. Để tương thích với FastMCP 2, mcp-clickhouse đọc các trường nhà cung cấp còn thiếu từ .env trong thư mục làm việc, nhưng phương án dự phòng tương thích đó không thể chọn FASTMCP_SERVER_AUTH. Một FASTMCP_ENV_FILE được đặt trong tiến trình thay thế phương án dự phòng tương thích đó và có thể cung cấp cả trường bộ chọn và nhà cung cấp. Đặt nó trước khi khởi động. Trình tải tương thích mcp-clickhouse chỉ đọc FASTMCP_SERVER_AUTH và FASTMCP_SERVER_AUTH_* từ tệp đó, vì vậy nó không thể chèn cài đặt CLICKHOUSE_*. FastMCP 4 có thể sử dụng cùng một tệp cho các cài đặt rộng hơn của riêng nó. Một nhà cung cấp tùy chỉnh không nhận đối số hàm tạo có nguồn gốc từ môi trường và phải hỗ trợ cấu trúc không có đối số.

Coi cả tệp .env được phát hiện và trong thư mục làm việc là cấu hình xác thực đáng tin cậy. Bất kỳ ai có thể tạo hoặc ghi một .env trong bất kỳ thư mục nào từ thư mục gói lên đến gốc hệ thống tệp đều có thể kiểm soát tệp nào được phát hiện, chọn nhà cung cấp và đặt các trường của nó. Bất kỳ ai có thể ghi tệp trong thư mục làm việc đều kiểm soát mọi trường nhà cung cấp không có trong tiến trình và cấu hình được phát hiện, bao gồm khóa ký, nhà phát hành và điểm cuối, cũng như bí mật máy khách. Một FASTMCP_ENV_FILE được đặt trong tiến trình trỏ đến một tệp thuộc sở hữu của nhà điều hành sẽ vô hiệu hóa phương án dự phòng thư mục làm việc.

FastMCP 4 đã thay đổi kho lưu trữ máy khách proxy OAuth mặc định. Các triển khai dựa trên lưu trữ proxy OAuth mặc định của FastMCP 2 phải đăng ký và ủy quyền lại cho máy khách. Lưu trữ tùy chỉnh tương thích, mã thông báo bearer tĩnh và xác minh JWT không bị ảnh hưởng.

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

Chỉ dành cho phát triển và thử nghiệm 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
export CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

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. Python 3.10 đến 3.14 được hỗ trợ. Python 3.12 được khuyến nghị cho các lần khởi chạy cục bộ.

  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.12",
        "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"
      }
    }
  }
}

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.12",
        "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"
      }
    }
  }
}

Đố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.12",
        "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.12",
        "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",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

  1. Xác định mục nhập 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 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 vô tình không thể xảy ra trong quá trình khám phá. Để cho phép câu lệnh DDL hoặc INSERT, đặt biến môi trường CLICKHOUSE_ALLOW_WRITE_ACCESS thành true. Máy chủ vẫn tiếp tục thực thi chế độ chỉ đọc nếu phiên bản ClickHouse tự nó không cho phép ghi.

Chế độ chỉ đọc vẫn cho phép người dùng ClickHouse hủy các truy vấn của chính họ, bao gồm cả các truy vấn từ các kết nối khác sử dụng cùng người dùng. Sử dụng người dùng ClickHouse chuyên dụng ngay cả trong chế độ chỉ đọc. Sử dụng các người dùng ClickHouse riêng biệt cho các khối lượng công việc không được phép hủy truy vấn của nhau.

Bảo vệ Thao tác Phá hủy

Ngay cả khi quyền ghi được bật (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), các thao tác phá hủy yêu cầu cờ chọn tham gia bổ sung để đảm bảo an toàn. Kiểm tra bao gồm bất kỳ câu lệnh DROP nào (bao gồm cả mệnh đề ALTER TABLE ... DROP PARTITION / DROP PART / DROP COLUMN), bất kỳ TRUNCATE, DELETE và UPDATE nào (cả câu lệnh nhẹ và biến đổi ALTER TABLE ... DELETE / ALTER TABLE ... UPDATE), REPLACE TABLE, CREATE OR REPLACE, ALTER TABLE ... REPLACE PARTITION, ALTER TABLE ... CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION, và DETACH ... PERMANENTLY. Các từ khóa bên trong chuỗi ký tự, định danh được trích dẫn, chú thích SQL và tên tham số {name:Type} bị bỏ qua, vì vậy chúng không kích hoạt kiểm tra cũng như không che giấu câu lệnh khỏi kiểm tra.

Kiểm tra này chạy trong máy chủ MCP và là biện pháp bảo vệ tốt nhất chống lại tai nạn. Nó không phải là ranh giới bảo mật. Ranh giới bảo mật là các quyền được cấp của người dùng ClickHouse. Chế độ chỉ đọc (mặc định) được thực thi phía máy chủ qua readonly=1. Cổng thao tác phá hủy không được thực thi phía máy chủ.

Đối với chế độ ghi, cấp cho máy chủ MCP một người dùng ClickHouse chuyên dụng chỉ với các quyền cần thiết:

CREATE USER mcp_agent IDENTIFIED BY '...';
GRANT SELECT, INSERT, CREATE TABLE, ALTER ADD COLUMN ON mydb.* TO mcp_agent;

Các thao tác thay đổi dữ liệu yêu cầu quyền ngoài các quyền được cấp này sẽ thất bại phía máy chủ với ACCESS_DENIED, bất kể cờ MCP. Cài đặt máy chủ max_table_size_to_drop và max_partition_size_to_drop cũng có thể giới hạn phạm vi ảnh hưởng nếu được ghim với các ràng buộc cài đặt.

Để bật các thao tác phá hủy, đặt cả hai cờ:

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

Phương pháp hai tầng này làm cho việc xóa vô tình trở nên khó khăn:

  • Thao tác ghi (INSERT, CREATE, ALTER ADD COLUMN) yêu cầu CLICKHOUSE_ALLOW_WRITE_ACCESS=true
  • Thao tác phá hủy (DROP, TRUNCATE, DELETE, UPDATE và phần còn lại của danh sách trên) bổ sung yêu cầu CLICKHOUSE_ALLOW_DROP=true

Chạy Không Có 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"
      }
    }
  }
}

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

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:

  • 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 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.12", "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).

Ví dụ Middleware

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ả yêu cầu MCP
  • Ghi nhật ký các lệnh gọi công cụ cụ thể
  • Đ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 thao tác MCP khác nhau:

  • on_message(context, call_next) - Được gọi cho tất cả thông điệp
  • on_request(context, call_next) - Được gọi cho tất cả yêu cầu
  • on_notification(context, call_next) - Được gọi cho tất 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, cùng 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 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 fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY


class ClientConfigMiddleware(Middleware):
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        ctx = get_context()
        await ctx.set_state(
            CLIENT_CONFIG_OVERRIDES_KEY,
            {
                "connect_timeout": 60,
                "send_receive_timeout": 120,
            },
            serializable=False,
        )
        return await call_next(context)

Đ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 theo từng người dùng.

Giá trị trạng thái phải là một từ điển. Các giá trị settings và generic_args lồng nhau phải là ánh xạ và được hợp nhất với cấu hình cơ sở. Các giá trị không hợp lệ làm cho lệnh gọi công cụ thất bại trước khi máy khách ClickHouse được tạo. CLICKHOUSE_ROLE vẫn hoạt động trừ khi ghi đè cung cấp rõ ràng settings.role. Các khóa cấp cao nhất role và ch_role, cùng các khóa tương tự dưới generic_args, bị từ chối.

Đặt verify, ca_cert, client_cert, client_cert_key, tls_mode, server_host_name, và pool_mgr chỉ dưới dạng ghi đè cấp cao nhất. Chúng không thể được lồng dưới generic_args. Một pool_mgr tùy chỉnh không thể được kết hợp với cài đặt CA được quản lý hoặc chứng chỉ máy khách. Tham số truy vấn DSN không thể đặt các khóa này và DSN không thể chọn backend chdb. Sử dụng các ghi đè cấp cao nhất tường minh host, port, username, password, database và secure để thay đổi kết nối. Một DSN được chuyển tiếp không thay thế các trường kết nối cơ sở đã được điền hoặc chọn TLS. Nó có thể điền các trường trống và cung cấp các tham số truy vấn được hỗ trợ như query_limit. Các ghi đè secure và verify chấp nhận boolean hoặc chuỗi true và false. verify cũng chấp nhận proxy, hoạt động như tls_mode: proxy khi tls_mode không được đặt và do đó sử dụng xác thực Basic với mật khẩu môi trường. Một ghi đè secure chọn giao diện https hoặc http khớp và không thay đổi cổng. Một ghi đè interface tường minh phải là http hoặc https và khớp với secure. Sau khi hợp nhất các ghi đè, các chế độ chứng chỉ máy khách mặc định và mutual bỏ qua mật khẩu. Các chế độ proxy và strict sử dụng xác thực Basic với mật khẩu môi trường trừ khi ghi đè cung cấp thông tin xác thực của riêng nó.

Coi các ghi đè này là đầu vào middleware đáng tin cậy. Middleware phải xác thực và ủy quyền các giá trị có nguồn gốc từ yêu cầu trước khi đặt chúng. Sử dụng serializable=False để FastMCP giữ giá trị trong trạng thái cục bộ yêu cầu. serializable=True mặc định lưu trữ trạng thái phiên và bị máy chủ từ chối. Máy chủ chụp nhanh giá trị trước khi phân phối công việc cơ sở dữ liệu chặn. Không lưu trữ dữ liệu đối tượng thuê trong trạng thái Ngữ cảnh có phạm vi phiên. Một ghi đè có phạm vi phiên bị từ chối vẫn được gắn vào phiên MCP kế thừa và khiến các lệnh gọi công cụ sau đó trong phiên đó thất bại cho đến khi máy khách kết nối lại. Một vai trò ClickHouse theo yêu cầu là cấu hình kết nối, không phải ranh giới ủy quyền đối tượng thuê. Thực thi cô lập đối tượng thuê bằng người dùng ClickHouse, vai trò và quyền được cấp.

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 ở gốc kho lưu trữ.

Lưu ý: Việc sử dụng người dùng default trong ngữ cảnh này chỉ nhằm 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, hãy 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 uv run fastmcp dev inspector mcp_clickhouse/mcp_server.py:mcp để khởi động máy chủ MCP.

  3. Để kiểm tra với giao thức HTTP và điểm kiểm tra sức khỏe:

    # For development, disable authentication
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000 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

Cấu trúc mã nguồn

Gói sử dụng cấu trúc mô-đun phẳng. Bắt đầu với mcp_server.py để lắp ráp và đăng ký máy chủ, sau đó theo dõi quá trình triển khai vào mô-đun sở hữu của nó.

Mô-đunTrách nhiệm
mcp_server.py, main.pyLắp ráp khởi động, đăng ký công cụ và lời nhắc, điều phối tắt máy và khởi động CLI
clients.pyCấu hình yêu cầu, kết nối ClickHouse được lưu trong bộ nhớ đệm và hợp đồng thuê máy khách
queries.pyThực thi truy vấn, hủy bỏ và bảo vệ các thao tác phá hủy
metadata.pyKhám phá cơ sở dữ liệu và bảng, mô hình siêu dữ liệu và phân trang
chdb_backend.py, chdb_prompt.pyKhởi tạo chDB tùy chọn, thực thi truy vấn và nội dung lời nhắc
health.py, executors.pyKiểm tra sức khỏe và bộ nhớ đệm, cùng các nhóm công nhân được sử dụng bởi các thao tác máy chủ
auth.py, transport.py, http_security.pyTải dotenv, xác thực, xây dựng ứng dụng HTTP/SSE và xác thực Host/Origin
mcp_env.py, serialization.pyCấu hình môi trường và mã hóa kết quả JSON
mcp_middleware_hook.py, skills_advisor.pyTải middleware tùy chỉnh và hướng dẫn máy chủ

Mỗi bộ lắp ráp máy chủ sở hữu các nhóm công nhân, bộ nhớ đệm máy khách, truy vấn đang hoạt động, bộ nhớ đệm phân trang, trạng thái sức khỏe và backend chDB. Việc dọn dẹp công nhân và máy khách chạy khi thoát tiến trình. Việc nhập gói khởi tạo máy chủ mặc định, bao gồm cả khi nhập mô-đun được trích xuất lần đầu.

Trong các bài kiểm tra, hãy vá mô-đun hoặc phiên bản sở hữu nơi mã đọc phụ thuộc. Ví dụ, vá mcp_clickhouse.clients.clickhouse_connect.get_client để tạo máy khách. Việc nhập tương thích trong mcp_server.py có thể là các ràng buộc riêng biệt với các ràng buộc mà một triển khai sử dụng.

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 các 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ác biến chứng chỉ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 / giao thứcCLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*, FASTMCP_ENV_FILEGiao thức 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

[!IMPORTANT] CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, CLICKHOUSE_CA_CERT, CLICKHOUSE_CLIENT_CERT, CLICKHOUSE_CLIENT_CERT_KEY, CLICKHOUSE_TLS_MODE và CLICKHOUSE_PORT chỉ áp dụng cho kết nối cơ sở dữ liệu ClickHouse đi ra. Chúng không cấu hình TLS, chứng chỉ máy khách, cổng hoặc xác thực cho điểm cuối MCP HTTP/SSE đi vào.

Ví dụ: nếu máy chủ MCP chạy trong Kubernetes phía sau một ingress kết thúc TLS, đó là vấn đề giao thức 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 ở phía sau ingress sẽ khiến máy chủ gọi ClickHouse qua HTTP—thường là với cổng chỉ HTTPS—và tạo ra các lỗi HTTP/TLS khó hiểu 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 máy khách HTTP clickhouse-connect và hành vi của các công cụ hỗ trợ ClickHouse như run_query, list_databases và list_tables. mcp-clickhouse yêu cầu clickhouse-connect 1.x, bắt đầu từ 1.0.0.

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
    • Bắt buộc trừ khi CLICKHOUSE_CLIENT_CERT sử dụng mặc định hoặc chế độ TLS "mutual"
    • Trong chế độ mặc định hoặc "mutual", xác thực chứng chỉ được sử dụng và mật khẩu không được gửi

[!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ỳ máy 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 quyền tối thiểu cần thiết cho hoạt động của nó. Việc sử dụng người dùng mặc định hoặc quản trị viên phải được tránh nghiêm ngặt mọi lúc.

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 sử dụng bởi máy chủ này và ClickHouse Cloud HTTPS
      • TCP gốc (không được hỗ trợ ở đây): 9000 (thường) / 9440 (TLS) — được sử dụng bởi clickhouse-client
    • 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 giá trị 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 phải cho máy khách MCP)
    • Mặc định: "true"
    • Đặt thành "false" chỉ khi máy chủ MCP tiếp cận 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 máy chủ MCP được hiển thị qua HTTP, stdio hoặc ingress kết thúc TLS riêng
    • Việc 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à lỗi thiết lập thường gặp và thường xuất hiện dưới dạng lỗi máy 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 sản xuất)
    • Chứng chỉ TLS: Gói sử dụng kho tin cậy hệ điều hành của bạn qua truststore.inject_into_ssl() khi khởi động. Xử lý SSL mặc định của Python được sử dụng nếu việc tiêm bị tắt bằng MCP_CLICKHOUSE_TRUSTSTORE_DISABLE=1 hoặc thất bại.
  • MCP_CLICKHOUSE_TRUSTSTORE_DISABLE: Tắt tích hợp kho tin cậy hệ điều hành trên toàn tiến trình cho TLS
    • Mặc định: không đặt (tích hợp kho tin cậy được bật)
    • Đặt chính xác thành "1" trước khi khởi động để bỏ qua truststore.inject_into_ssl() và sử dụng xử lý chứng chỉ SSL mặc định của Python. Các giá trị khác không tắt tích hợp.
    • Điều này không tắt xác minh chứng chỉ. CLICKHOUSE_VERIFY vẫn kiểm soát xác minh cho kết nối HTTPS ClickHouse.
  • CLICKHOUSE_CA_CERT: Đường dẫn đến gói chứng chỉ CA PEM cho kết nối HTTPS ClickHouse
    • Mặc định: Không có (sử dụng kho tin cậy hệ điều hành trừ khi tiêm truststore bị tắt hoặc thất bại)
    • Sử dụng riêng biến này khi máy chủ ClickHouse hoặc proxy riêng trình bày chứng chỉ được ký bởi CA riêng. Điều này thay đổi xác minh chứng chỉ máy chủ và không bật xác thực chứng chỉ máy khách.
    • Yêu cầu CLICKHOUSE_SECURE=true và CLICKHOUSE_VERIFY=true
  • CLICKHOUSE_CLIENT_CERT: Đường dẫn đến chứng chỉ máy khách PEM cho kết nối HTTPS ClickHouse
    • Mặc định: Không có
    • Tệp cũng có thể chứa khóa riêng. Nếu không, hãy đặt CLICKHOUSE_CLIENT_CERT_KEY.
    • Người dùng ClickHouse vẫn đến từ CLICKHOUSE_USER.
  • CLICKHOUSE_CLIENT_CERT_KEY: Đường dẫn đến khóa riêng PEM cho CLICKHOUSE_CLIENT_CERT
    • Mặc định: Không có
    • Tùy chọn khi khóa riêng được bao gồm trong tệp chứng chỉ máy khách
    • Không thể sử dụng mà không có CLICKHOUSE_CLIENT_CERT
  • CLICKHOUSE_TLS_MODE: Cách clickhouse-connect sử dụng CLICKHOUSE_CLIENT_CERT
    • Mặc định: Không có, hoạt động như "mutual" khi chứng chỉ máy khách được đặt
    • "mutual": Sử dụng chứng chỉ máy khách để xác thực người dùng X.509 ClickHouse. CLICKHOUSE_PASSWORD là tùy chọn và không được gửi.
    • "proxy": Trình bày chứng chỉ máy khách cho proxy kết thúc TLS, sau đó sử dụng xác thực Cơ bản ClickHouse. CLICKHOUSE_PASSWORD là bắt buộc.
    • "strict": Trình bày chứng chỉ máy khách vì máy chủ ClickHouse yêu cầu một chứng chỉ ở lớp TLS, sau đó sử dụng xác thực Cơ bản ClickHouse. CLICKHOUSE_PASSWORD là bắt buộc. Chế độ này không tăng cường xác minh chứng chỉ máy chủ. CLICKHOUSE_VERIFY kiểm soát xác minh đó.
    • clickhouse-connect xử lý "proxy" và "strict" giống hệt nhau. Hai tên ghi lại ý định.
    • Các giá trị được cắt bớt và không phân biệt chữ hoa chữ thường. Giá trị trống được coi là không đặt. Các giá trị khác bị từ chối trước khi máy khách ClickHouse được tạo, tại lần gọi công cụ ClickHouse đầu tiên hoặc kiểm tra /health.
    • Yêu cầu CLICKHOUSE_CLIENT_CERT. Tất cả các tùy chọn chứng chỉ máy khách đều yêu cầu CLICKHOUSE_SECURE=true.
  • CLICKHOUSE_SERVER_HOST_NAME: Tên máy chủ máy chủ để 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)
    • Hữu ích khi kết nối 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ỉ báo tên máy chủ) trong 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 giá trị này khi giao diện HTTP ClickHouse được hiển thị phía sau proxy ngược dưới 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 máy khách ClickHouse
    • Mặc định: "30"
    • Tăng giá trị này nếu bạn gặp 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 máy khách ClickHouse
    • Mặc định: giá trị thấp hơn của 300 hoặc CLICKHOUSE_MCP_QUERY_TIMEOUT + 5, để các luồng công nhân bỏ chặn ngay sau thời gian chờ truy vấn
    • Nếu được đặt rõ ràng, giá trị được sử dụng nguyên trạng (ví dụ: "300" 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 giá trị này để tự động kết nối đến 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 DDL và DML không phá hủy (CREATE, INSERT, ALTER ADD COLUMN). Các câu lệnh phá hủy bổ sung cần CLICKHOUSE_ALLOW_DROP=true
    • Khi bị tắt (mặc định), các truy vấn chạy với cài đặt readonly=1 để ngăn sửa đổi dữ liệu
  • CLICKHOUSE_ALLOW_DROP: Cho phép các thao tác phá hủy (bất kỳ DROP hoặc TRUNCATE, DELETE và UPDATE bao gồm các biến thể ALTER TABLE, REPLACE TABLE / REPLACE PARTITION / CREATE OR REPLACE, CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION và DETACH ... PERMANENTLY)
    • Mặc định: "false"
    • Chỉ có hiệu lực khi CLICKHOUSE_ALLOW_WRITE_ACCESS=true cũng được đặt
    • Cổng này là bảo vệ tai nạn nỗ lực tốt nhất trong máy chủ MCP, không phải ranh giới bảo mật. Hạn chế quyền của người dùng ClickHouse để thực thi thực sự (xem Bảo vệ thao tác phá hủy)
Tệp chứng chỉ TLS ClickHouse

Các biến chứng chỉ chứa đường dẫn tệp, không phải nội dung PEM. mcp-clickhouse truyền các đường dẫn này đến clickhouse-connect. Đối với Docker hoặc Kubernetes, hãy gắn chứng chỉ và khóa riêng dưới dạng tệp chỉ đọc và sử dụng đường dẫn của chúng bên trong container. Không nhúng khóa riêng vào image, không commit nó vào hệ thống kiểm soát mã nguồn, hoặc đặt nội dung của nó trong biến môi trường.

Trong chế độ mutual, chứng chỉ máy khách được cấu hình xác định tiến trình mcp-clickhouse này là CLICKHOUSE_USER. Nó không xác thực các máy khách MCP đến hoặc truyền danh tính của chúng đến ClickHouse. Cấu hình xác thực truyền tải MCP riêng biệt.

Khởi động lại mcp-clickhouse sau khi thay thế chứng chỉ hoặc khóa tại cùng một đường dẫn khi cần luân chuyển hoặc thu hồi ngay lập tức. Các máy khách được lưu trong bộ nhớ cache có thể giữ lại các kết nối TLS hiện có và bộ nhớ cache không theo dõi nội dung tệp hoặc thời gian sửa đổi.

ClickHouse Cloud không hỗ trợ xác thực chứng chỉ máy khách X.509 cho người dùng cơ sở dữ liệu. Sử dụng CLICKHOUSE_USER và CLICKHOUSE_PASSWORD cho ClickHouse Cloud. Chứng chỉ CA vẫn có thể hữu ích khi một proxy riêng phía trước điểm cuối trình bày chứng chỉ được ký bởi CA riêng.

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

Các biến này kiểm soát 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ị trình lắng nghe mạng (liên kết máy chủ/cổng bên dưới)
    • "sse" chọn truyền tải HTTP+SSE độc lập đã lỗi thời và ghi nhật ký cảnh báo. Sử dụng "http" cho Streamable HTTP trong các triển khai mớ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 lệnh gọi 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
    • Khi truy vấn hết thời gian chờ, máy chủ cố gắng hủy nó bằng KILL QUERY
    • Trừ khi CLICKHOUSE_SEND_RECEIVE_TIMEOUT được đặt rõ ràng, thời gian chờ đọc HTTP được giới hạn ở giá trị này cộng thêm năm giây
  • CLICKHOUSE_MCP_MAX_WORKERS: Số lượng tối đa các luồng công nhân truy vấn đồng thời
    • Mặc định: "10"
    • Tăng nếu khối lượng công việc của bạn yêu cầu nhiều lệnh gọi công cụ đồng thời
    • Các công cụ siêu dữ liệu sử dụng một nhóm riêng với min(4, CLICKHOUSE_MCP_MAX_WORKERS) luồng để khám phá lược đồ không thể trì hoãn các truy vấn
  • CLICKHOUSE_MCP_AUTH_TOKEN: Mã thông báo 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 uuidgen hoặc openssl rand -hex 32
    • Máy khách phải gửi mã thông báo này trong tiêu đề Authorization: Bearer <token>
  • FASTMCP_SERVER_AUTH: Ủy quyền xác thực cho 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, mcp-clickhouse tải nhà cung cấp từ các biến môi trường FASTMCP_SERVER_AUTH_* hiện có; để trống CLICKHOUSE_MCP_AUTH_TOKEN trong chế độ này
    • Các nhà cung cấp tùy chỉnh không nhận được đối số hàm tạo có nguồn gốc từ môi trường và phải hỗ trợ xây dựng không đối số
    • FastMCP 4 không còn hỗ trợ xác minh Supabase HS256. Các triển khai Supabase phải sử dụng RS256 hoặc ES256.
  • FASTMCP_ENV_FILE: Tệp tùy chọn chứa FASTMCP_SERVER_AUTH và các biến môi trường dành riêng cho nhà cung cấp
    • Mặc định: Không có. Khi không được đặt, trình tải tương thích đọc các trường nhà cung cấp còn thiếu từ .env trong thư mục làm việc. Nó không đọc FASTMCP_SERVER_AUTH từ dự phòng đó
    • Đặt nó trong môi trường tiến trình trước khi khởi động. Một giá trị được tải từ .env mặc định không thể chuyển hướng trình tải tương thích
    • Nếu được đặt bởi tiến trình, tệp này có thể cung cấp cả FASTMCP_SERVER_AUTH và các trường nhà cung cấp và thay thế dự phòng thư mục làm việc
    • Các giá trị môi trường tiến trình có quyền ưu tiên không phân biệt chữ hoa chữ thường
    • Trình tải tương thích mcp-clickhouse chỉ đọc tệp này khi xây dựng xác thực HTTP/SSE và chỉ đọc các mục FASTMCP_SERVER_AUTH và FASTMCP_SERVER_AUTH_*. FastMCP 4 có thể đọc cùng một tệp cho các cài đặt rộng hơn của nó
    • Việc tải .env mặc định là riêng biệt. Nó bắt đầu tại thư mục gói mcp_clickhouse đã cài đặt, giải quyết các liên kết tượng trưng, đi lên đến gốc hệ thống tệp và tải .env đầu tiên được tìm thấy hoặc không có gì. Nó không bao giờ đọc thư mục làm việc, bất kể phương thức khởi chạy. Tệp đó có thể cung cấp FASTMCP_SERVER_AUTH và các trường nhà cung cấp cùng với các cài đặt máy chủ khác. Một bản kiểm tra mã nguồn thường tìm thấy .env gốc của kho lưu trữ
  • CLICKHOUSE_MCP_AUTH_DISABLED: Vô hiệu hóa 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" để vô hiệu hóa xác thực chỉ cho phát triển/thử nghiệm cục bộ
    • CẢNH BÁO: Chỉ sử dụng cho phát triển cục bộ. Không vô hiệu hóa khi tiếp xúc với mạng
  • CLICKHOUSE_MCP_ALLOWED_HOSTS: Các giá trị tiêu đề Host được phân tách bằng dấu phẩy mà máy chủ HTTP/SSE trả lời
    • Mặc định cho liên kết loopback: dạng trần và dạng bất kỳ cổng nào của 127.0.0.1, localhost và [::1]
    • Nếu được đặt, giá trị phải chứa ít nhất một mục Host.
    • Một địa chỉ liên kết cụ thể không phải loopback mặc định là địa chỉ đó và cổng được cấu hình. Một liên kết đại diện như 0.0.0.0 hoặc :: yêu cầu một giá trị không trống rõ ràng vì Host công khai không thể được suy ra.
    • Xác thực Host là một lớp bảo vệ chống lại DNS rebinding. Xác thực nguồn gốc bên dưới được MCP yêu cầu riêng biệt.
    • Các mục là chính xác (localhost:8000) hoặc chấp nhận bất kỳ cổng nào (localhost:*). Ví dụ: CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000
    • Dạng host:* chỉ khớp với các giá trị mang cổng. Một Host không có cổng (triển khai cổng tiêu chuẩn nơi máy khách bỏ qua :80/:443) phải được liệt kê dưới dạng mục chính xác trần (example.com) nữa.
    • Các yêu cầu có tiêu đề Host không khớp hoặc thiếu nhận được 421 Misdirected Request. Các yêu cầu GET và HEAD đến /health được miễn xác thực Host và Origin để các trình thăm dò điều phối tiếp tục hoạt động.
    • Đằng sau proxy ngược, ưu tiên giữ nguyên tiêu đề Host gốc. Bạn có thể thay vào đó liệt kê giá trị Host thượng nguồn mà proxy gửi. Đặt danh sách rõ ràng khi một trình khởi chạy như fastmcp run ghi đè địa chỉ liên kết để truy cập từ xa.
    • mcp-clickhouse buộc tắt bảo vệ Host và Origin riêng của FastMCP. FASTMCP_HTTP_HOST_ORIGIN_PROTECTION, FASTMCP_HTTP_ALLOWED_HOSTS và FASTMCP_HTTP_ALLOWED_ORIGINS không áp dụng. CLICKHOUSE_MCP_ALLOWED_HOSTS và CLICKHOUSE_MCP_ALLOWED_ORIGINS có thẩm quyền.
  • CLICKHOUSE_MCP_TRUSTED_PROXIES: Địa chỉ IP proxy hoặc mạng CIDR có tiêu đề X-Forwarded-* được tin cậy
    • Mặc định: Không có. X-Forwarded-Host bị bỏ qua. Xử lý Uvicorn hiện có của X-Forwarded-For và X-Forwarded-Proto không thay đổi.
    • Các mục phải là địa chỉ IP hoặc mạng CIDR, chẳng hạn như 127.0.0.1,10.20.0.0/24,2001:db8::1. CIDR phải sử dụng địa chỉ mạng của chúng, vì vậy 10.20.0.1/24 bị từ chối. Tên máy chủ, địa chỉ IPv6 có phạm vi, *, 0.0.0.0/0 và ::/0 cũng bị từ chối.
    • Sự tin cậy dựa trên đối tác socket thô ngay lập tức. Một yêu cầu từ bất kỳ đối tác nào khác hoặc yêu cầu không có địa chỉ máy khách sẽ bỏ qua X-Forwarded-Host và xác thực Host.
    • Một đối tác được tin cậy có thể gửi chính xác một tiêu đề X-Forwarded-Host chứa một giá trị không trống. Các trường trùng lặp, giá trị trống và danh sách phân tách bằng dấu phẩy nhận được 421 Misdirected Request. Nếu tiêu đề vắng mặt, Host được xác thực.
    • Sử dụng địa chỉ hoặc mạng hẹp nhất có thể. Máy chủ MCP chỉ được truy cập thông qua các proxy trong các phạm vi được cấu hình. Mỗi proxy được tin cậy phải loại bỏ và ghi đè các giá trị X-Forwarded-Host và X-Forwarded-Proto do máy khách cung cấp và xây dựng X-Forwarded-For từ đối tác kết nối đã xác minh.
    • Máy chủ tích hợp và fastmcp run vô hiệu hóa xử lý tiêu đề proxy bên ngoài của Uvicorn, xác thực Host từ đối tác thô, sau đó áp dụng X-Forwarded-For và X-Forwarded-Proto. Bật rõ ràng uvicorn_config["proxy_headers"] sẽ làm cho việc khởi động thất bại trong chế độ này.
    • Việc nhúng ASGI trực tiếp phải vô hiệu hóa xử lý tiêu đề proxy trong máy chủ ASGI bên ngoài và gọi mcp.http_app(raw_client_address_preserved=True). Nếu không có xác nhận rõ ràng đó, việc xây dựng ứng dụng sẽ thất bại khi các proxy được tin cậy được cấu hình.
  • CLICKHOUSE_MCP_ALLOWED_ORIGINS: Các giá trị tiêu đề Origin được phân tách bằng dấu phẩy được chấp nhận trên HTTP/SSE
    • Mặc định: Không có, từ chối mọi yêu cầu mang tiêu đề Origin
    • MCP yêu cầu xác thực Origin cho các kết nối truyền tải HTTP/SSE. Các yêu cầu không có Origin được chấp nhận vì các máy khách MCP không phải trình duyệt thường bỏ qua nó. Một Origin không khớp nhận được 403 Forbidden. Điểm cuối /health được miễn như mô tả ở trên.
    • Các mục là chính xác (http://localhost:3000) hoặc chấp nhận bất kỳ cổng nào (http://localhost:*). Như với máy chủ, dạng bất kỳ cổng nào chỉ khớp với các nguồn gốc mang cổng; một nguồn gốc cổng tiêu chuẩn (https://app.example.com) phải được liệt kê chính xác.
Xử lý Host proxy ngược

Giữ nguyên Host khi có thể. Điều này giữ cho việc tin cậy Host được chuyển tiếp bị vô hiệu hóa:

location / {
    proxy_pass http://mcp-clickhouse:8000;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Host "";
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Vệ sinh X-Forwarded-For và X-Forwarded-Proto độc lập với sự tin cậy X-Forwarded-Host. Uvicorn có thể tin cậy các tiêu đề đó dựa trên đối tác proxy ngay cả khi CLICKHOUSE_MCP_TRUSTED_PROXIES không được đặt.

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com

nginx tiêu chuẩn thay đổi Host thành tên thượng nguồn cho các yêu cầu được proxy. Nó không tạo hoặc ghi đè X-Forwarded-Host. Nếu không thể giữ nguyên Host, hãy ghi đè tiêu đề được chuyển tiếp tại biên được tin cậy:

location / {
    proxy_pass http://mcp-clickhouse:8000;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com
CLICKHOUSE_MCP_TRUSTED_PROXIES=10.20.0.8

Cấu hình thứ hai chỉ an toàn khi 10.20.0.8 là địa chỉ nguồn ngay lập tức của proxy, cổng máy chủ được cách ly khỏi các máy khách khác và nginx ghi đè các tiêu đề chuyển tiếp đến như được hiển thị. Đối với một chuỗi proxy, mỗi bước nhảy được tin cậy phải loại bỏ các giá trị đến chưa được xác minh trước khi xây dựng các tiêu đề chuyển tiếp mới.

Trên liên kết IPv6 hoặc dual-stack, các proxy IPv4 có thể xuất hiện dưới dạng địa chỉ ánh xạ IPv4 như ::ffff:10.20.0.8; chúng được khớp tự động với các mục IPv4. append_x_forwarded_host của Envoy nối thêm vào X-Forwarded-Host hiện có thay vì ghi đè nó, tạo ra một danh sách phân tách bằng dấu phẩy bị từ chối, vì vậy hãy cấu hình bước nhảy được tin cậy để ghi đè tiêu đề thay thế. Trên Kubernetes với NAT nguồn (ví dụ: externalTrafficPolicy: Cluster), đối tác quan sát được có thể là IP nút thay vì pod proxy, vì vậy hãy tin cậy CIDR pod hoặc nút khi thích hợp; ingress-nginx tự ghi đè cả Host và X-Forwarded-Host.

Biến Middleware

  • MCP_MIDDLEWARE_MODULE: Tên mô-đun Python chứa middleware tùy chỉnh để chèn vào máy chủ MCP
    • Mặc định: Không có (không có middleware được tải)
    • Đặ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 gói 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 để lưu trữ bền vững (ví dụ: /path/to/chdb/data)

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

  • CLICKHOUSE_SECURE so với MCP / TLS cổng vào — Tắt CLICKHOUSE_SECURE vì máy chủ MCP nằm sau cổng vào Kubernetes, proxy ngược hoặc được truy cập qua HTTP thông thường không vô hiệu hóa TLS của cơ sở dữ liệu; nó chỉ thay đổi cách tiến trình này kết nối đến ClickHouse. Cấu hình TLS cổng vào riêng biệt với cài đặt máy khách cơ sở dữ liệu.
  • Cổng giao thức gốc — CLICKHOUSE_PORT phải nhắm đến 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ụ

Đối với 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

Đối với 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

Đối với ClickHouse SQL Playground:

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

Đối với CA máy chủ riêng tư mà không có xác thực chứng chỉ máy khách:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-user
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_VERIFY=true
CLICKHOUSE_CA_CERT=/run/secrets/clickhouse-ca.pem

Đối với xác thực chứng chỉ máy khách X.509 của ClickHouse:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-certificate-user
CLICKHOUSE_SECURE=true
CLICKHOUSE_CLIENT_CERT=/run/secrets/clickhouse-client.pem
CLICKHOUSE_CLIENT_CERT_KEY=/run/secrets/clickhouse-client-key.pem
# CLICKHOUSE_CA_CERT=/run/secrets/clickhouse-ca.pem  # Only for a private server CA
# CLICKHOUSE_TLS_MODE=mutual  # Optional. This is the default with a client certificate.

Đối với chứng chỉ máy khách được yêu cầu bởi máy chủ TLS nghiêm ngặt trong khi ClickHouse sử dụng xác thực Basic:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-user
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_CLIENT_CERT=/run/secrets/clickhouse-client.pem
CLICKHOUSE_CLIENT_CERT_KEY=/run/secrets/clickhouse-client-key.pem
CLICKHOUSE_TLS_MODE=strict

Sử dụng CLICKHOUSE_TLS_MODE=proxy thay thế khi proxy kết thúc TLS yêu cầu chứng chỉ máy khách và ClickHouse vẫn sử dụng xác thực Basic.

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

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

Đối với chDB có lưu trữ bền vững:

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

Đối với MCP Inspector hoặc truy cập từ xa với giao thức 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)
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:4200,localhost:4200,mcp.example.com:4200  # Include every Host value clients and proxies send

Đối với phát triển cục bộ với giao thức HTTP (xác thực bị vô hiệu hóa):

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

Khi sử dụng giao thức 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:8000/mcp
  • Kiểm tra sức khỏe: http://localhost:8000/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.12",
        "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ủ liên kết và cổng chỉ được sử dụng khi giao thức đượ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 về YouTube

YouTube