ClickHouse

ทางการ

สอบถามเซิร์ฟเวอร์ฐานข้อมูล ClickHouse ของคุณ

GitHub
839

คุณทำอะไรได้บ้างด้วย Click House MCP?

  • รันคำสั่ง SQL แบบอ่านอย่างเดียว — ขอให้ผู้ช่วยดำเนินการ SELECT query ใดๆ กับคลัสเตอร์ ClickHouse ของคุณโดยใช้ run_query
  • แสดงรายการฐานข้อมูลและตาราง — สำรวจ schema ของคุณโดยแสดงรายการฐานข้อมูลทั้งหมดด้วย list_databases หรือแบ่งหน้าตารางในฐานข้อมูลเฉพาะด้วย list_tables
  • สอบถามไฟล์และ URL โดยตรงผ่าน chDB — ใช้ run_chdb_select_query เพื่อรัน SQL กับไฟล์ในเครื่องหรือแหล่งข้อมูลระยะไกลโดยไม่ต้องโหลดเข้าสู่ ClickHouse ก่อน
  • ควบคุมการเขียนและการดำเนินการที่ทำลายข้อมูล — เปิดใช้งาน CLICKHOUSE_ALLOW_WRITE_ACCESS สำหรับ DDL/DML และเลือกเปิด CLICKHOUSE_ALLOW_DROP เพื่ออนุญาตคำสั่ง DROP หรือ TRUNCATE ในระหว่างเซสชันที่ใช้ AI ช่วยเหลือ

เอกสาร

ClickHouse MCP Server

PyPI - Version

เซิร์ฟเวอร์ MCP สำหรับ ClickHouse

mcp-clickhouse MCP server

คุณสมบัติ

เครื่องมือ ClickHouse

  • run_query

    • รันคำสั่ง SQL บนคลัสเตอร์ ClickHouse ของคุณ
    • อินพุต: query (string): คำสั่ง SQL ที่ต้องการรัน
    • คำสั่งจะทำงานในโหมดอ่านอย่างเดียวโดยค่าเริ่มต้น (CLICKHOUSE_ALLOW_WRITE_ACCESS=false) แต่สามารถเปิดใช้งานการเขียนได้อย่างชัดเจนหากจำเป็น

  • list_databases

    • แสดงรายการฐานข้อมูลทั้งหมดบนคลัสเตอร์ ClickHouse ของคุณ

  • list_tables

    • แสดงรายการตารางในฐานข้อมูลพร้อมการแบ่งหน้า
    • อินพุตที่จำเป็น: database (string)
    • อินพุตเสริม:
      • like / not_like (string): ใช้ตัวกรอง LIKE หรือ NOT LIKE กับชื่อตาราง
      • page_token (string): โทเค็นที่ส่งคืนจากการเรียกก่อนหน้าเพื่อดึงหน้าถัดไป
      • page_size (int, ค่าเริ่มต้น 50): จำนวนตารางที่ส่งคืนต่อหน้า
      • include_detailed_columns (bool, ค่าเริ่มต้น true): เมื่อเป็น false จะละเว้นข้อมูลเมตาของคอลัมน์เพื่อการตอบสนองที่เบากว่า แต่ยังคง create_table_query ไว้ครบถ้วน
    • รูปแบบการตอบสนอง:
      • tables: อาร์เรย์ของออบเจกต์ตารางสำหรับหน้าปัจจุบัน
      • next_page_token: ส่งค่านี้กลับไปเพื่อดึงหน้าถัดไป หรือ null เมื่อไม่มีตารางเหลือแล้ว
      • total_tables: จำนวนตารางทั้งหมดที่ตรงกับตัวกรองที่ให้มา

เครื่องมือ chDB

  • run_chdb_select_query
    • รันคำสั่ง SQL โดยใช้เอนจิน ClickHouse แบบฝังตัวของ chDB
    • อินพุต: query (string): คำสั่ง SQL ที่ต้องการรัน
    • สืบค้นข้อมูลโดยตรงจากแหล่งต่างๆ (ไฟล์, URL, ฐานข้อมูล) โดยไม่ต้องผ่านกระบวนการ ETL
    • ต้องการ chdb extra ที่เป็นทางเลือก: pip install 'mcp-clickhouse[chdb]'

ปลายทางตรวจสอบความสมบูรณ์

เมื่อทำงานด้วยการขนส่ง HTTP หรือ SSE จะมีปลายทางตรวจสอบความสมบูรณ์ที่ /health ปลายทางนี้:

  • ส่งคืน 200 OK (body: OK) หากเซิร์ฟเวอร์ทำงานปกติและสามารถเชื่อมต่อกับ ClickHouse ได้
  • ส่งคืน 503 Service Unavailable พร้อมข้อความแสดงข้อผิดพลาดทั่วไป หากเซิร์ฟเวอร์ไม่สามารถเชื่อมต่อกับ ClickHouse ได้

ปลายทางนี้ไม่มีการตรวจสอบสิทธิ์โดยเจตนา เพื่อให้โพรบจากตัวจัดการ (เช่น Kubernetes liveness/readiness, load balancers) สามารถเข้าถึงได้โดยไม่ต้องใช้ข้อมูลประจำตัว เนื้อหาการตอบสนองถูกทำให้เหลือน้อยที่สุดโดยเจตนาเพื่อหลีกเลี่ยงการรั่วไหลของสตริงเวอร์ชันแบ็กเอนด์หรือรายละเอียดข้อผิดพลาด ให้ตรวจแก้จุดบกพร่องความล้มเหลวผ่านบันทึกของเซิร์ฟเวอร์

ตัวอย่าง:

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

ความปลอดภัย

การตรวจสอบสิทธิ์สำหรับการขนส่ง HTTP/SSE

เมื่อใช้การขนส่ง HTTP หรือ SSE จำเป็นต้องมีการตรวจสอบสิทธิ์ตามค่าเริ่มต้น การขนส่ง stdio (ค่าเริ่มต้น) ไม่จำเป็นต้องมีการตรวจสอบสิทธิ์ เนื่องจากสื่อสารผ่านอินพุต/เอาต์พุตมาตรฐานเท่านั้น

รองรับโหมดการตรวจสอบสิทธิ์สามแบบ เลือกอย่างใดอย่างหนึ่ง:

โหมดเมื่อใดที่ควรใช้ตัวแปรสภาพแวดล้อม
โทเค็น bearer แบบคงที่การปรับใช้แบบง่าย, บริการภายในCLICKHOUSE_MCP_AUTH_TOKEN
OAuth / OIDC (ผ่าน FastMCP)Azure Entra, Google, GitHub, WorkOS, ฯลฯFASTMCP_SERVER_AUTH=<provider-class-path> (+ ตัวแปร FASTMCP_SERVER_AUTH_* เฉพาะของผู้ให้บริการ)
ปิดใช้งานการพัฒนาในเครื่องเท่านั้นCLICKHOUSE_MCP_AUTH_DISABLED=true

การเริ่มต้นจะล้มเหลวหากไม่มีการกำหนดค่าใดๆ เหล่านี้สำหรับการขนส่ง HTTP/SSE

การตั้งค่าการตรวจสอบสิทธิ์

  1. สร้างโทเค็นที่ปลอดภัย (สามารถเป็นสตริงสุ่มใดๆ ก็ได้):

    # Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

  2. กำหนดค่าเซิร์ฟเวอร์ด้วยโทเค็น:

    export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

  3. กำหนดค่าไคลเอนต์ MCP ของคุณให้รวมโทเค็นในคำขอ:

    สำหรับ Claude Desktop ที่ใช้การขนส่ง HTTP/SSE:

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

    หมายเหตุ: ปลายทาง /health ไม่มีการตรวจสอบสิทธิ์โดยเจตนา (ดู ปลายทางตรวจสอบความสมบูรณ์ ด้านบน) เพื่อตรวจสอบว่าการตรวจสอบสิทธิ์ด้วยโทเค็น bearer ปฏิเสธคำขอที่ไม่ได้รับอนุญาตจริงหรือไม่ ให้เข้าถึงปลายทาง MCP โดยตรง เช่น ด้วย MCP Inspector หรือโดยการ POST คำขอ JSON-RPC ไปยัง /mcp ทั้งที่มีและไม่มีส่วนหัว Authorization และยืนยันว่าการเรียกที่ไม่ได้รับอนุญาตส่งคืน 401

OAuth / OIDC ผ่าน FastMCP

สำหรับการปรับใช้ในสภาพแวดล้อมจริงที่มีผู้ให้บริการข้อมูลประจำตัว (Azure Entra, Google, GitHub, WorkOS, ฯลฯ) ให้มอบหมายการตรวจสอบสิทธิ์ให้กับ ผู้ให้บริการการตรวจสอบสิทธิ์ในตัวของ FastMCP แทนการใช้โทเค็นแบบคงที่ ตั้งค่า FASTMCP_SERVER_AUTH เป็น พาธคลาสแบบเต็ม ของผู้ให้บริการการตรวจสอบสิทธิ์ FastMCP พร้อมกับตัวแปร FASTMCP_SERVER_AUTH_* เฉพาะของผู้ให้บริการ และปล่อย CLICKHOUSE_MCP_AUTH_TOKEN ว่างไว้

ตัวอย่าง (Azure Entra):

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

ดู เอกสาร FastMCP สำหรับรายชื่อผู้ให้บริการทั้งหมดและตัวแปรสภาพแวดล้อมที่จำเป็น

โหมดการพัฒนา (ปิดใช้งานการตรวจสอบสิทธิ์)

สำหรับการพัฒนาและทดสอบในเครื่องเท่านั้น คุณสามารถปิดใช้งานการตรวจสอบสิทธิ์ได้โดยตั้งค่า:

export CLICKHOUSE_MCP_AUTH_DISABLED=true

คำเตือน: ใช้สำหรับการพัฒนาในเครื่องเท่านั้น อย่าปิดใช้งานการตรวจสอบสิทธิ์เมื่อเซิร์ฟเวอร์ถูกเปิดเผยต่อเครือข่ายใดๆ

การกำหนดค่า

เซิร์ฟเวอร์ MCP นี้รองรับทั้ง ClickHouse และ chDB คุณสามารถเปิดใช้งานอย่างใดอย่างหนึ่งหรือทั้งสองอย่างได้ตามความต้องการของคุณ

  1. เปิดไฟล์การกำหนดค่า Claude Desktop ที่อยู่:

    • บน macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • บน Windows: %APPDATA%/Claude/claude_desktop_config.json

  2. เพิ่มสิ่งต่อไปนี้:

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

อัปเดตตัวแปรสภาพแวดล้อมให้ชี้ไปยังบริการ ClickHouse ของคุณเอง

หรือหากคุณต้องการทดลองใช้กับ ClickHouse SQL Playground คุณสามารถใช้การกำหนดค่าต่อไปนี้:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

สำหรับ chDB (เอนจิน ClickHouse แบบฝังตัว) ให้เพิ่มการกำหนดค่าต่อไปนี้:

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

คุณยังสามารถเปิดใช้งานทั้ง ClickHouse และ chDB พร้อมกันได้:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

  1. ค้นหารายการคำสั่งสำหรับ uv และแทนที่ด้วยพาธสัมบูรณ์ไปยังไฟล์ปฏิบัติการ uv เพื่อให้แน่ใจว่ามีการใช้ uv เวอร์ชันที่ถูกต้องเมื่อเริ่มต้นเซิร์ฟเวอร์ บน mac คุณสามารถค้นหาพาธนี้ได้โดยใช้ which uv

  2. รีสตาร์ท Claude Desktop เพื่อใช้การเปลี่ยนแปลง

การเข้าถึงการเขียนที่เป็นทางเลือก

ตามค่าเริ่มต้น MCP นี้จะบังคับใช้คำสั่งอ่านอย่างเดียว เพื่อไม่ให้เกิดการเปลี่ยนแปลงโดยไม่ตั้งใจระหว่างการสำรวจ หากต้องการอนุญาตคำสั่ง DDL หรือ INSERT/UPDATE ให้ตั้งค่าตัวแปรสภาพแวดล้อม CLICKHOUSE_ALLOW_WRITE_ACCESS เป็น true เซิร์ฟเวอร์จะยังคงบังคับใช้โหมดอ่านอย่างเดียวหากอินสแตนซ์ ClickHouse เองไม่อนุญาตให้เขียน

การป้องกันการดำเนินการทำลายล้าง

แม้ว่าจะเปิดใช้งานการเข้าถึงการเขียน (CLICKHOUSE_ALLOW_WRITE_ACCESS=true) แล้ว การดำเนินการทำลายล้าง (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) จำเป็นต้องมีแฟล็กการยินยอมเพิ่มเติมเพื่อความปลอดภัย ซึ่งจะป้องกันการลบข้อมูลโดยไม่ตั้งใจระหว่างการสำรวจด้วย AI

ในการเปิดใช้งานการดำเนินการทำลายล้าง ให้ตั้งค่าทั้งสองแฟล็ก:

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

แนวทางสองระดับนี้ช่วยให้แน่ใจว่าการทำลายโดยไม่ตั้งใจเป็นเรื่องยากมาก:

  • การดำเนินการเขียน (INSERT, UPDATE, CREATE) ต้องการ CLICKHOUSE_ALLOW_WRITE_ACCESS=true
  • การดำเนินการทำลายล้าง (DROP, TRUNCATE) ต้องการ CLICKHOUSE_ALLOW_DROP=true เพิ่มเติม

การรันโดยไม่ใช้ uv (ใช้ System Python)

หากคุณต้องการใช้การติดตั้ง Python ของระบบแทน uv คุณสามารถติดตั้งแพ็คเกจจาก PyPI และรันได้โดยตรง:

  1. ติดตั้งแพ็คเกจโดยใช้ pip:

    python3 -m pip install mcp-clickhouse

    เพื่อติดตั้งการรองรับ chDB ด้วย:

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

    เพื่ออัปเกรดเป็นเวอร์ชันล่าสุด:

    python3 -m pip install --upgrade mcp-clickhouse

  2. อัปเดตการกำหนดค่า Claude Desktop ของคุณให้ใช้ Python โดยตรง:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "python3",
      "args": [
        "-m",
        "mcp_clickhouse.main"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

หรือคุณสามารถใช้สคริปต์ที่ติดตั้งไว้ได้โดยตรง:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "mcp-clickhouse",
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

หมายเหตุ: ตรวจสอบให้แน่ใจว่าใช้พาธแบบเต็มไปยังไฟล์ปฏิบัติการ Python หรือสคริปต์ mcp-clickhouse หากไม่อยู่ใน PATH ของระบบ คุณสามารถค้นหาพาธได้โดยใช้:

  • which python3 สำหรับไฟล์ปฏิบัติการ Python
  • which mcp-clickhouse สำหรับสคริปต์ที่ติดตั้ง

มิดเดิลแวร์แบบกำหนดเอง

คุณสามารถเพิ่มมิดเดิลแวร์แบบกำหนดเองไปยังเซิร์ฟเวอร์ MCP ได้โดยไม่ต้องแก้ไขซอร์สโค้ด FastMCP มีระบบมิดเดิลแวร์ที่ช่วยให้คุณสามารถดักจับและประมวลผลข้อความโปรโตคอล MCP (การเรียกใช้เครื่องมือ, การอ่านทรัพยากร, พรอมต์, ฯลฯ)

วิธีใช้

  1. สร้างโมดูล Python ด้วยคลาสมิดเดิลแวร์ที่ขยาย Middleware และฟังก์ชัน setup_middleware(mcp):
# my_middleware.py
import logging
from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext

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

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

def setup_middleware(mcp):
    """Register middleware with the MCP server."""
    mcp.add_middleware(LoggingMiddleware())
  1. ตั้งค่าตัวแปรสภาพแวดล้อม MCP_MIDDLEWARE_MODULE เป็นชื่อโมดูล (โดยไม่มีนามสกุล .py):
{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}
  1. ตรวจสอบให้แน่ใจว่าโมดูลมิดเดิลแวร์ของคุณอยู่ในพาธการนำเข้าของ Python (เช่น ในไดเรกทอรีเดียวกับที่เซิร์ฟเวอร์ MCP ทำงาน หรือติดตั้งเป็นแพ็คเกจ)

ตัวอย่างมิดเดิลแวร์

มีโมดูลมิดเดิลแวร์ตัวอย่างให้ใน example_middleware.py ซึ่งแสดงรูปแบบทั่วไป:

  • การบันทึกคำขอ MCP ทั้งหมด
  • การบันทึกการเรียกใช้เครื่องมือโดยเฉพาะ
  • การวัดเวลาการประมวลผลคำขอ

วิธีใช้ตัวอย่าง:

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

ความสามารถของมิดเดิลแวร์

คลาสพื้นฐาน Middleware มี hooks สำหรับการดำเนินการ MCP ต่างๆ:

  • on_message(context, call_next) - เรียกใช้สำหรับข้อความทั้งหมด
  • on_request(context, call_next) - เรียกใช้สำหรับคำขอทั้งหมด
  • on_notification(context, call_next) - เรียกใช้สำหรับการแจ้งเตือนทั้งหมด
  • on_call_tool(context, call_next) - เรียกใช้เมื่อมีการเรียกใช้เครื่องมือ
  • on_read_resource(context, call_next) - เรียกใช้เมื่อมีการอ่านทรัพยากร
  • on_get_prompt(context, call_next) - เรียกใช้เมื่อมีการเรียกค้นพรอมต์
  • on_list_tools(context, call_next) - เรียกใช้เมื่อแสดงรายการเครื่องมือ
  • on_list_resources(context, call_next) - เรียกใช้เมื่อแสดงรายการทรัพยากร
  • on_list_resource_templates(context, call_next) - เรียกใช้เมื่อแสดงรายการเทมเพลตทรัพยากร
  • on_list_prompts(context, call_next) - เรียกใช้เมื่อแสดงรายการพรอมต์

แต่ละ hook ได้รับออบเจกต์ MiddlewareContext ที่ประกอบด้วยข้อความและข้อมูลเมตา และฟังก์ชัน call_next เพื่อดำเนินการไปป์ไลน์ต่อไป

การกำหนดค่าไคลเอนต์แบบไดนามิกผ่าน Context State

มิดเดิลแวร์สามารถแทนที่การกำหนดค่าไคลเอนต์ ClickHouse ตามแต่ละคำขอได้ โดยใช้คีย์สถานะบริบท CLIENT_CONFIG_OVERRIDES_KEY เซิร์ฟเวอร์จะรวมการแทนที่เหล่านี้เข้ากับการกำหนดค่าพื้นฐานจากตัวแปรสภาพแวดล้อม

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

สิ่งนี้ช่วยให้เกิดกรณีการใช้งานขั้นสูง เช่น การปรับไทม์เอาต์แบบไดนามิก, การกำหนดเส้นทางเฉพาะผู้เช่า หรือการตั้งค่าการเชื่อมต่อต่อผู้ใช้

การพัฒนา

  1. ในไดเรกทอรี test-services รัน docker compose up -d เพื่อเริ่มคลัสเตอร์ ClickHouse

  2. เพิ่มตัวแปรต่อไปนี้ลงในไฟล์ .env ในรูทของที่เก็บ

หมายเหตุ: การใช้ผู้ใช้ default ในบริบทนี้มีจุดประสงค์เพื่อการพัฒนาในเครื่องเท่านั้น

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

  1. รัน uv sync เพื่อติดตั้งการพึ่งพา ในการติดตั้ง uv ให้ทำตามคำแนะนำ ที่นี่ จากนั้นทำ source .venv/bin/activate

  2. เพื่อการทดสอบที่ง่ายดายด้วย MCP Inspector ให้รัน fastmcp dev mcp_clickhouse/mcp_server.py เพื่อเริ่มเซิร์ฟเวอร์ MCP

  3. เพื่อทดสอบด้วยการขนส่ง HTTP และปลายทางตรวจสอบความสมบูรณ์:

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

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

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

ตัวแปรสภาพแวดล้อม

การกำหนดค่าถูกแบ่งออกเป็นกลุ่มที่เป็นอิสระต่อกัน การผสมกันเป็นสาเหตุทั่วไปของความล้มเหลวในการเชื่อมต่อที่แก้จุดบกพร่องได้ยาก:

กลุ่มตัวแปรควบคุม
การเชื่อมต่อฐานข้อมูล ClickHouseCLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, …วิธีที่เซิร์ฟเวอร์ MCP นี้เชื่อมต่อกับคลัสเตอร์ ClickHouse ของคุณผ่านอินเทอร์เฟซ HTTP
เซิร์ฟเวอร์ MCP / การขนส่งCLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*การขนส่ง MCP, การตรวจสอบสิทธิ์ และขีดจำกัดการเรียกใช้เครื่องมือสืบค้น
มิดเดิลแวร์ / chDBMCP_MIDDLEWARE_MODULE, CHDB_*ส่วนขยายที่เป็นทางเลือก

[!IMPORTANT] ตัวแปรเช่น CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY และ CLICKHOUSE_PORT ใช้กับการเชื่อมต่อฐานข้อมูล ClickHouse เท่านั้น ตัวแปรเหล่านี้ไม่ได้กำหนดค่า TLS, พอร์ต หรือการตรวจสอบสิทธิ์สำหรับปลายทางโปรโตคอล MCP

ตัวอย่าง: หากเซิร์ฟเวอร์ MCP ทำงานใน Kubernetes หลัง ingress ที่สิ้นสุด TLS นั่นเป็นข้อกังวลของการขนส่ง MCP ให้รักษา CLICKHOUSE_SECURE ให้สอดคล้องกับวิธีที่พ็อดเข้าถึง ClickHouse เอง (HTTPS → true, plain HTTP → false) การตั้งค่า CLICKHOUSE_SECURE=false เนื่องจากเซิร์ฟเวอร์ MCP อยู่หลัง ingress จะทำให้เซิร์ฟเวอร์ต่อสายไปยัง ClickHouse ผ่าน HTTP—ซึ่งมักจะต่อกับพอร์ต HTTPS เท่านั้น—และทำให้เกิดข้อผิดพลาด HTTP/TLS ที่ไม่ชัดเจนในบันทึกของเซิร์ฟเวอร์

การเชื่อมต่อฐานข้อมูล ClickHouse

ตัวแปรเหล่านี้กำหนดค่าไคลเอนต์ HTTP clickhouse-connect และพฤติกรรมของเครื่องมือที่ใช้ ClickHouse เป็นแบ็กเอนด์ เช่น run_query, list_databases และ list_tables

ตัวแปรที่จำเป็น
  • CLICKHOUSE_HOST: ชื่อโฮสต์ของเซิร์ฟเวอร์ ClickHouse ของคุณ (ปลายทางฐานข้อมูล ไม่ใช่ที่อยู่การเชื่อมต่อของเซิร์ฟเวอร์ MCP)
  • CLICKHOUSE_USER: ชื่อผู้ใช้สำหรับการตรวจสอบสิทธิ์ ClickHouse
  • CLICKHOUSE_PASSWORD: รหัสผ่านสำหรับการตรวจสอบสิทธิ์ ClickHouse

[!CAUTION] สิ่งสำคัญคือต้องปฏิบัติต่อผู้ใช้ฐานข้อมูล MCP ของคุณเช่นเดียวกับไคลเอนต์ภายนอกใดๆ ที่เชื่อมต่อกับฐานข้อมูลของคุณ โดยให้สิทธิ์ขั้นต่ำที่จำเป็นสำหรับการดำเนินงานเท่านั้น ควรหลีกเลี่ยงการใช้ผู้ใช้เริ่มต้นหรือผู้ดูแลระบบอย่างเคร่งครัดตลอดเวลา

ตัวแปรเสริม
  • CLICKHOUSE_PORT: พอร์ตอินเทอร์เฟซ HTTP ของเซิร์ฟเวอร์ ClickHouse ของคุณ
    • ค่าเริ่มต้น: 8443 หาก CLICKHOUSE_SECURE=true, 8123 หาก CLICKHOUSE_SECURE=false
    • โดยปกติไม่จำเป็นต้องตั้งค่า เว้นแต่จะใช้พอร์ตที่ไม่ได้มาตรฐาน
    • ต้องเป็นพอร์ตอินเทอร์เฟซ HTTP ไม่ใช่พอร์ตโปรโตคอล TCP ดั้งเดิมที่ใช้โดย clickhouse-client
    • ค่าทั่วไป:
      • HTTP: 8123 (ธรรมดา) / 8443 (TLS) — ใช้โดยเซิร์ฟเวอร์นี้และ ClickHouse Cloud HTTPS
      • Native TCP (ไม่รองรับที่นี่): 9000 (ธรรมดา) / 9440 (TLS) — ใช้โดย clickhouse-client
    • หากเซิร์ฟเวอร์ตอบสนองด้วย Port 9000 is for clickhouse-client program แสดงว่าคุณกำลังชี้ไปที่โปรโตคอลดั้งเดิม ให้เปลี่ยนไปใช้พอร์ต HTTP (8123/8443 หรือการแมป HTTP ของการปรับใช้ของคุณ)
  • CLICKHOUSE_ROLE: บทบาท ClickHouse ที่จะใช้สำหรับการตรวจสอบสิทธิ์
    • ค่าเริ่มต้น: ไม่มี
    • ตั้งค่านี้หากผู้ใช้ของคุณต้องการบทบาทเฉพาะ
  • CLICKHOUSE_SECURE: เปิดใช้งาน HTTPS สำหรับการเชื่อมต่อฐานข้อมูล ClickHouse (ไม่ใช่สำหรับไคลเอนต์ MCP)
    • ค่าเริ่มต้น: "true"
    • ตั้งค่าเป็น "false" เฉพาะเมื่อเซิร์ฟเวอร์ MCP เข้าถึง ClickHouse ผ่าน HTTP ธรรมดา (โดยทั่วไปสำหรับ Docker Compose ในเครื่องบนพอร์ต 8123)
    • ปล่อยให้เป็น "true" สำหรับ ClickHouse Cloud และปลายทางฐานข้อมูล HTTPS ใดๆ แม้ว่าเซิร์ฟเวอร์ MCP เองจะถูกเปิดเผยผ่าน HTTP, stdio หรือ ingress ที่สิ้นสุด TLS แยกต่างหาก
    • การตั้งค่าสถานะนี้ไม่ตรงกับพอร์ตฐานข้อมูล (เช่น CLICKHOUSE_SECURE=false กับพอร์ต 8443) เป็นข้อผิดพลาดในการตั้งค่าที่พบบ่อย และมักจะแสดงเป็นข้อผิดพลาดของไคลเอนต์ HTTP ที่สับสน แทนที่จะเป็นข้อความ "รูปแบบผิด" ที่ชัดเจน
  • CLICKHOUSE_VERIFY: เปิด/ปิดใช้งานการตรวจสอบใบรับรอง SSL สำหรับการเชื่อมต่อ HTTPS ของ ClickHouse
    • ค่าเริ่มต้น: "true"
    • ตั้งค่าเป็น "false" เพื่อปิดใช้งานการตรวจสอบใบรับรอง (ไม่แนะนำสำหรับการใช้งานจริง)
    • ใบรับรอง TLS: แพ็คเกจใช้ที่เก็บความน่าเชื่อถือของระบบปฏิบัติการของคุณสำหรับการตรวจสอบใบรับรอง TLS ผ่าน truststore เราเรียก truststore.inject_into_ssl() เมื่อเริ่มต้นเพื่อให้แน่ใจว่ามีการจัดการใบรับรองที่เหมาะสม พฤติกรรม SSL เริ่มต้นของ Python ถูกใช้เป็นทางเลือกสำรองเฉพาะเมื่อเกิดข้อผิดพลาดที่ไม่คาดคิด
  • CLICKHOUSE_SERVER_HOST_NAME: ชื่อโฮสต์เซิร์ฟเวอร์สำหรับการแทนที่ SNI และการตรวจสอบใบรับรองในการเชื่อมต่อ ClickHouse
    • ค่าเริ่มต้น: ไม่มี (ใช้ชื่อโฮสต์การเชื่อมต่อ)
    • สิ่งนี้มีประโยชน์เมื่อเชื่อมต่อผ่านพร็อกซีหรือตัวจัดสรรภาระงานที่ชื่อโฮสต์ของใบรับรองแตกต่างจากชื่อโฮสต์การเชื่อมต่อ เมื่อตั้งค่าแล้ว ชื่อโฮสต์นี้จะถูกใช้สำหรับทั้ง SNI (การระบุชื่อเซิร์ฟเวอร์) ระหว่างการจับมือ TLS และสำหรับการตรวจสอบชื่อโฮสต์ของใบรับรอง
  • CLICKHOUSE_PROXY_PATH: คำนำหน้าเส้นทาง URL สำหรับปลายทาง HTTP ของ ClickHouse
    • ค่าเริ่มต้น: ไม่มี
    • ตั้งค่านี้เมื่ออินเทอร์เฟซ HTTP ของ ClickHouse ถูกเปิดเผยหลังพร็อกซีย้อนกลับภายใต้คำนำหน้าเส้นทาง (ตัวอย่างเช่น /clickhouse)
  • CLICKHOUSE_CONNECT_TIMEOUT: ระยะหมดเวลาการเชื่อมต่อเป็นวินาทีสำหรับไคลเอนต์ ClickHouse
    • ค่าเริ่มต้น: "30"
    • เพิ่มค่านี้หากคุณพบปัญหาการหมดเวลาการเชื่อมต่อ
  • CLICKHOUSE_SEND_RECEIVE_TIMEOUT: ระยะหมดเวลาการส่ง/รับเป็นวินาทีสำหรับไคลเอนต์ ClickHouse
    • ค่าเริ่มต้น: "300"
    • เพิ่มค่านี้สำหรับคิวรีที่ทำงานเป็นเวลานาน
  • CLICKHOUSE_DATABASE: ฐานข้อมูล ClickHouse เริ่มต้นที่จะใช้
    • ค่าเริ่มต้น: ไม่มี (ใช้ค่าเริ่มต้นของเซิร์ฟเวอร์)
    • ตั้งค่านี้เพื่อเชื่อมต่อกับฐานข้อมูลเฉพาะโดยอัตโนมัติ
  • CLICKHOUSE_ENABLED: เปิด/ปิดใช้งานเครื่องมือฐานข้อมูล ClickHouse
    • ค่าเริ่มต้น: "true"
    • ตั้งค่าเป็น "false" เพื่อปิดใช้งานเครื่องมือ ClickHouse เมื่อใช้ chDB เท่านั้น
  • CLICKHOUSE_ALLOW_WRITE_ACCESS: อนุญาตการดำเนินการเขียน (DDL และ DML) กับ ClickHouse
    • ค่าเริ่มต้น: "false"
    • ตั้งค่าเป็น "true" เพื่ออนุญาตการดำเนินการ DDL (CREATE, ALTER, DROP) และ DML (INSERT, UPDATE, DELETE)
    • เมื่อปิดใช้งาน (ค่าเริ่มต้น) คิวรีจะทำงานด้วยการตั้งค่า readonly=1 เพื่อป้องกันการแก้ไขข้อมูล
  • CLICKHOUSE_ALLOW_DROP: อนุญาตการดำเนินการทำลายล้าง (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE)
    • ค่าเริ่มต้น: "false"
    • มีผลเฉพาะเมื่อตั้งค่า CLICKHOUSE_ALLOW_WRITE_ACCESS=true ด้วย
    • ตั้งค่าเป็น "true" เพื่ออนุญาตการดำเนินการ DROP และ TRUNCATE ที่ทำลายล้างอย่างชัดเจน
    • นี่คือคุณลักษณะด้านความปลอดภัยเพื่อป้องกันการลบข้อมูลโดยไม่ตั้งใจระหว่างการสำรวจของ AI

เซิร์ฟเวอร์ MCP และการขนส่ง

ตัวแปรเหล่านี้ควบคุมกระบวนการ MCP เอง รวมถึงการขนส่ง การตรวจสอบสิทธิ์ และขีดจำกัดการดำเนินการของเครื่องมือคิวรี ซึ่งเป็นอิสระจากการตั้งค่าฐานข้อมูล ClickHouse ข้างต้น ดูเพิ่มเติมที่ การตรวจสอบสิทธิ์สำหรับการขนส่ง HTTP/SSE

  • CLICKHOUSE_MCP_SERVER_TRANSPORT: ตั้งค่าวิธีการขนส่งสำหรับเซิร์ฟเวอร์ MCP
    • ค่าเริ่มต้น: "stdio"
    • ตัวเลือกที่ถูกต้อง: "stdio", "http", "sse" สิ่งนี้มีประโยชน์สำหรับการพัฒนาในเครื่องด้วยเครื่องมือเช่น MCP Inspector
    • stdio เป็นเรื่องปกติสำหรับ Claude Desktop; http/sse เปิดเผยตัวรับฟังเครือข่าย (โฮสต์/พอร์ตการเชื่อมต่อด้านล่าง)
  • CLICKHOUSE_MCP_BIND_HOST: โฮสต์ที่จะเชื่อมต่อเซิร์ฟเวอร์ MCP เมื่อใช้การขนส่ง HTTP หรือ SSE
    • ค่าเริ่มต้น: "127.0.0.1"
    • ตั้งค่าเป็น "0.0.0.0" เพื่อเชื่อมต่อกับอินเทอร์เฟซเครือข่ายทั้งหมด (มีประโยชน์สำหรับ Docker หรือการเข้าถึงระยะไกล)
    • ใช้เฉพาะเมื่อการขนส่งเป็น "http" หรือ "sse" — ไม่เกี่ยวข้องกับ CLICKHOUSE_HOST
  • CLICKHOUSE_MCP_BIND_PORT: พอร์ตที่จะเชื่อมต่อเซิร์ฟเวอร์ MCP เมื่อใช้การขนส่ง HTTP หรือ SSE
    • ค่าเริ่มต้น: "8000"
    • ใช้เฉพาะเมื่อการขนส่งเป็น "http" หรือ "sse" — ไม่เกี่ยวข้องกับ CLICKHOUSE_PORT
  • CLICKHOUSE_MCP_QUERY_TIMEOUT: ระยะหมดเวลาเป็นวินาทีสำหรับเครื่องมือคิวรี
    • ค่าเริ่มต้น: "30"
    • เพิ่มค่านี้หากคุณเห็นข้อผิดพลาด Query timed out after ... สำหรับคิวรีหนัก
  • CLICKHOUSE_MCP_AUTH_TOKEN: โทเค็น bearer แบบคงที่สำหรับการขนส่ง HTTP/SSE
    • ค่าเริ่มต้น: ไม่มี
    • จำเป็นต้องมีหนึ่งใน CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH หรือ CLICKHOUSE_MCP_AUTH_DISABLED=true สำหรับการขนส่ง HTTP/SSE
    • สร้างโดยใช้ uuidgen หรือ openssl rand -hex 32
    • ไคลเอนต์ต้องส่งโทเค็นนี้ในส่วนหัว Authorization: Bearer <token>
  • FASTMCP_SERVER_AUTH: มอบหมายการตรวจสอบสิทธิ์ให้กับ ผู้ให้บริการตรวจสอบสิทธิ์ FastMCP
    • ค่าเริ่มต้น: ไม่มี
    • ค่าคือ เส้นทางคลาสแบบเต็ม ของคลาสย่อย AuthProvider เช่น fastmcp.server.auth.providers.azure.AzureProvider หรือ fastmcp.server.auth.providers.google.GoogleProvider
    • เมื่อตั้งค่าแล้ว FastMCP จะโหลดผู้ให้บริการโดยอัตโนมัติจากตัวแปรสภาพแวดล้อม FASTMCP_SERVER_AUTH_* ของตัวเอง ปล่อยให้ CLICKHOUSE_MCP_AUTH_TOKEN ไม่ได้ตั้งค่าในโหมดนี้
  • CLICKHOUSE_MCP_AUTH_DISABLED: ปิดใช้งานการตรวจสอบสิทธิ์สำหรับการขนส่ง HTTP/SSE
    • ค่าเริ่มต้น: "false" (เปิดใช้งานการตรวจสอบสิทธิ์)
    • ตั้งค่าเป็น "true" เพื่อปิดใช้งานการตรวจสอบสิทธิ์สำหรับการพัฒนา/ทดสอบในเครื่องเท่านั้น
    • คำเตือน: ใช้สำหรับการพัฒนาในเครื่องเท่านั้น อย่าปิดใช้งานเมื่อเปิดเผยต่อเครือข่าย

ตัวแปรมิดเดิลแวร์

  • MCP_MIDDLEWARE_MODULE: ชื่อโมดูล Python ที่มีมิดเดิลแวร์แบบกำหนดเองเพื่อแทรกลงในเซิร์ฟเวอร์ MCP
    • ค่าเริ่มต้น: ไม่มี (ไม่มีการโหลดมิดเดิลแวร์)
    • ตั้งค่าเป็นชื่อโมดูล (ไม่มีนามสกุล .py) ของโมดูลมิดเดิลแวร์ของคุณ
    • โมดูลต้องมีฟังก์ชัน setup_middleware(mcp)
    • ดู มิดเดิลแวร์แบบกำหนดเอง สำหรับรายละเอียดและตัวอย่าง

ตัวแปร chDB

  • CHDB_ENABLED: เปิด/ปิดใช้งานฟังก์ชันการทำงานของ chDB
    • ค่าเริ่มต้น: "false"
    • ตั้งค่าเป็น "true" เพื่อเปิดใช้งานเครื่องมือ chDB
    • ต้องติดตั้งส่วนเสริมเพิ่มเติม: mcp-clickhouse[chdb]
  • CHDB_DATA_PATH: เส้นทางไปยังไดเรกทอรีข้อมูล chDB
    • ค่าเริ่มต้น: ":memory:" (ฐานข้อมูลในหน่วยความจำ)
    • ใช้ :memory: สำหรับฐานข้อมูลในหน่วยความจำ
    • ใช้เส้นทางไฟล์สำหรับการจัดเก็บข้อมูลถาวร (เช่น /path/to/chdb/data)

ข้อผิดพลาดในการกำหนดค่าทั่วไป

  • CLICKHOUSE_SECURE กับ MCP / ingress TLS — การปิด CLICKHOUSE_SECURE เนื่องจากเซิร์ฟเวอร์ MCP อยู่หลัง Kubernetes ingress, พร็อกซีย้อนกลับ หรือเข้าถึงผ่าน HTTP ธรรมดา ไม่ได้ปิดใช้งาน TLS ของฐานข้อมูล แต่จะเปลี่ยนเฉพาะวิธีที่กระบวนการนี้เชื่อมต่อกับ ClickHouse กำหนดค่า ingress TLS แยกต่างหากจากการตั้งค่าไคลเอนต์ฐานข้อมูล
  • พอร์ตโปรโตคอลดั้งเดิม — CLICKHOUSE_PORT ต้องกำหนดเป้าหมายไปที่อินเทอร์เฟซ HTTP ของ ClickHouse (8123/8443 ตามค่าเริ่มต้น) พอร์ต 9000/9440 มีไว้สำหรับโปรโตคอล TCP ดั้งเดิม (clickhouse-client) และจะไม่ทำงานกับเซิร์ฟเวอร์นี้
  • ความสับสนของโฮสต์ — CLICKHOUSE_HOST คือชื่อโฮสต์ฐานข้อมูล CLICKHOUSE_MCP_BIND_HOST เป็นเพียงที่อยู่ที่เซิร์ฟเวอร์ MCP HTTP/SSE รับฟัง

ตัวอย่างการกำหนดค่า

สำหรับการพัฒนาในเครื่องด้วย Docker:

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

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

สำหรับ ClickHouse Cloud:

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

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

สำหรับ ClickHouse SQL Playground:

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

สำหรับ chDB เท่านั้น (ในหน่วยความจำ):

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

สำหรับ chDB พร้อมการจัดเก็บข้อมูลถาวร:

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

สำหรับ MCP Inspector หรือการเข้าถึงระยะไกลด้วยการขนส่ง 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)

สำหรับการพัฒนาในเครื่องด้วยการขนส่ง HTTP (ปิดใช้งานการตรวจสอบสิทธิ์):

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

เมื่อใช้การขนส่ง HTTP เซิร์ฟเวอร์จะทำงานบนพอร์ตที่กำหนดค่าไว้ (ค่าเริ่มต้น 8000) ตัวอย่างเช่น ด้วยการกำหนดค่าข้างต้น:

  • ปลายทาง MCP: http://localhost:4200/mcp
  • การตรวจสอบความสมบูรณ์: http://localhost:4200/health

คุณสามารถตั้งค่าตัวแปรเหล่านี้ในสภาพแวดล้อมของคุณ ในไฟล์ .env หรือในการกำหนดค่า Claude Desktop:

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

หมายเหตุ: การตั้งค่าโฮสต์และพอร์ตการเชื่อมต่อจะใช้เฉพาะเมื่อตั้งค่าการขนส่งเป็น "http" หรือ "sse"

การรันการทดสอบ

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

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

ภาพรวม YouTube

YouTube