ClickHouse

ทางการ

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

GitHub
899

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

  • รันคิวรี SQL — สั่งให้ดำเนินการคิวรี SQL ใดๆ บนคลัสเตอร์ ClickHouse ของคุณผ่าน run_query พร้อมพารามิเตอร์แบบระบุชื่อได้ผ่าน params
  • แสดงรายการฐานข้อมูล — ค้นหาฐานข้อมูลทั้งหมดที่มีบนคลัสเตอร์ ClickHouse ของคุณโดยใช้ list_databases
  • เรียกดูตารางพร้อมตัวกรอง — ใช้ list_tables เพื่อสำรวจตารางในฐานข้อมูล โดยใช้รูปแบบ like/not_like และการแบ่งหน้าผ่าน page_token และ page_size
  • ตรวจสอบโครงร่างคิวรี — ขอ DESCRIBE (<query>) หรือ EXPLAIN ESTIMATE <query> ผ่าน run_query เพื่อตรวจสอบคอลัมน์ผลลัพธ์หรือการอ่านโดยประมาณก่อนดำเนินการ
  • คิวรีข้อมูล chDB ที่ฝังอยู่ — รัน SQL กับเอ็นจินที่ฝังอยู่ของ chDB โดยตรงเพื่อคิวรีไฟล์, URL หรือฐานข้อมูลโดยไม่ต้องใช้ ETL โดยใช้ run_chdb_select_query

เอกสาร

ClickHouse MCP Server

PyPI - Version

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

mcp-clickhouse MCP server

เซิร์ฟเวอร์นี้ใช้งาน MCP 2026-07-28 และรองรับการจับมือเริ่มต้นแบบเดิมจาก 2024-11-05 ถึง 2025-11-25 ไคลเอนต์สมัยใหม่ใช้คำขอแบบไม่มีเซสชันและ server/discover ไคลเอนต์ที่มีอยู่สามารถเจรจาโปรโตคอลแบบเดิมต่อไปได้

[!NOTE] คำขอ HTTP ที่ไม่มี MCP-Protocol-Version จะถูกส่งผ่านการจัดการแบบเดิมเพื่อให้ ไคลเอนต์จากก่อน 2025-06-18 ยังคงเชื่อมต่อได้ MCP 2026-07-28 อนุญาต พฤติกรรมนี้บนเซิร์ฟเวอร์ที่รองรับไคลเอนต์เหล่านั้น ไคลเอนต์สมัยใหม่ควรส่ง ส่วนหัวในทุกคำขอ POST

คุณสมบัติ

เครื่องมือ ClickHouse

การตอบสนองของเครื่องมือ ClickHouse เป็นสตริงที่เข้ารหัส JSON จำนวนเต็มที่อยู่นอก [-9007199254740991, 9007199254740991] จะถูกส่งกลับเป็นสตริงทศนิยมเพื่อรักษาค่าที่แม่นยำ ในไคลเอนต์ JavaScript สิ่งนี้ใช้กับแถวผลลัพธ์ของคิวรีและเมทาดาทาของตารางที่เป็นจำนวนเต็ม จำนวนเต็มและบูลีนในช่วงปลอดภัยจะคงประเภท JSON ไว้

  • run_query

    • ดำเนินการคิวรี SQL บนคลัสเตอร์ ClickHouse ของคุณ
    • อินพุต: query (สตริง): คิวรี SQL ที่จะดำเนินการ
    • อินพุตเสริม: params (ออบเจกต์): ค่าที่มีชื่อสำหรับตัวยึดตำแหน่ง {name:Type} ของ ClickHouse ดู พารามิเตอร์คิวรี
    • คิวรีทำงานในโหมดอ่านอย่างเดียวโดยค่าเริ่มต้น (CLICKHOUSE_ALLOW_WRITE_ACCESS=false) แต่สามารถเปิดใช้งานการเขียนได้อย่างชัดเจนหากจำเป็น
    • DESCRIBE (<query>) และ EXPLAIN ESTIMATE <query> ทำงานที่นี่เช่นกันและเป็นวิธีเสริมในการตรวจสอบสคีมาผลลัพธ์ของคิวรีหรือการอ่านโดยประมาณ ดู การตรวจสอบคิวรีก่อนดำเนินการ

  • list_databases

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

  • list_tables

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

การค้นพบสคีมาของ Agents

คำแนะนำของเซิร์ฟเวอร์แนะนำให้อ่าน Agents Schema's canonical AGENTS.ROOT ถึง run_query เมื่อ list_databases เผยให้เห็นฐานข้อมูล AGENTS ก่อนเขียน SQL เชิงวิเคราะห์ นี่เป็นคำแนะนำสำหรับเอเจนต์: ไม่มีการดึงเมทาดาทา โดยอัตโนมัติ ผลลัพธ์ของเครื่องมือไม่เปลี่ยนแปลง และสิทธิ์ ClickHouse ที่มีอยู่ยังคงมีผล หาก AGENTS.ROOT หายไปหรือไม่สามารถเข้าถึงได้ การค้นพบ และคิวรีปกติยังคงใช้งานได้

พารามิเตอร์คิวรี

ส่งค่าต่างหากจาก SQL ผ่านออบเจกต์ params เสริม:

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

ใช้ตัวยึดตำแหน่ง {name:Type} ของ ClickHouse โดยไม่ต้องใส่เครื่องหมายคำพูด เก็บวงเล็บเปิด ชื่อ และเครื่องหมายโคลอนให้ติดกัน เช่น {id:UInt32} รองรับช่องว่างหลังเครื่องหมายโคลอน และภายในประเภท เช่น {id: UInt32} และ {amount:Decimal(18, 4)} เพื่อความเข้ากันได้กับเวอร์ชันไดรเวอร์ที่รองรับ ให้เริ่มชื่อด้วยตัวอักษรหรือ ขีดล่าง และใช้เฉพาะตัวอักษร ตัวเลข และขีดล่าง การจัดรูปแบบแบบ Python %s หรือ %(name)s และพารามิเตอร์ไบนารีดิบ $name$ ของไดรเวอร์ ไม่รองรับ การเรียกที่มีเฉพาะ query ยังคงทำงาน การละเว้น params การส่ง null หรือการส่งออบเจกต์ว่างจะทำให้คิวรีไม่ถูกผูก

ค่าพารามิเตอร์สามารถเป็นสตริง JSON ตัวเลข บูลีน null หรืออาร์เรย์ โดยต้อง ตรงกับประเภท ClickHouse ที่ประกาศ:

  • ใช้ null กับประเภท Nullable(...)
  • ส่งจำนวนเต็มที่แน่นอนนอกช่วงปลอดภัยของ JavaScript เป็นสตริงทศนิยม เช่น "18446744073709551615" กับ {id:UInt64} วันที่ ประทับเวลา และทศนิยมที่แน่นอน สามารถส่งเป็นสตริงพร้อมประเภท ClickHouse ที่สอดคล้องกันได้
  • ผูกเวกเตอร์เป็นอาร์เรย์เดียว เช่น {vector:Array(Float32)} กับ "params": {"vector": [0.25, 0.5, 0.75]}
  • ค่า null ภายในอาร์เรย์ขึ้นอยู่กับไดรเวอร์ที่ติดตั้ง ทำงานกับ clickhouse-connect 1.8.0 แต่ล้มเหลวกับเวอร์ชันขั้นต่ำที่รองรับ 1.0.0
  • รายการและออบเจกต์ JSON ไม่สามารถผูกกับประเภท Tuple และ Map ของ ClickHouse ได้

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

ค่าพารามิเตอร์ไม่อยู่ในข้อความบันทึก SQL ปกติของเซิร์ฟเวอร์ MCP แต่ยังคง อยู่ในอาร์กิวเมนต์ของเครื่องมือ MCP และอาจปรากฏในข้อผิดพลาดแบ็กเอนด์ ClickHouse 26.3.20.7 แทนที่ค่าลงในข้อความคิวรีใน system.query_log, system.processes และ system.text_log การผูกพารามิเตอร์ไม่ใช่คุณสมบัติความเป็นส่วนตัวและไม่ ลดจำนวนค่าของเวกเตอร์ที่ส่งในการเรียกเครื่องมือ

การตรวจสอบคิวรีก่อนดำเนินการ

run_query ยังรัน DESCRIBE และ EXPLAIN ESTIMATE ทั้งสองเป็นการตรวจสอบเสริม: ใช้ DESCRIBE เมื่อคุณต้องการคอลัมน์ผลลัพธ์และประเภทของคิวรี และใช้ EXPLAIN ESTIMATE ก่อน SELECT ที่อาจมีค่าใช้จ่ายสูง

DESCRIBE (<query>) ตรวจสอบสคีมาผลลัพธ์และส่งคืนเมทาดาทาของคอลัมน์ผลลัพธ์เดียวกันกับ 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 ต้องวิเคราะห์คิวรีเพื่อตอบ ดังนั้นข้อผิดพลาดการวิเคราะห์จะปรากฏที่นี่ พร้อมข้อความของ ClickHouse เอง แทนที่จะปรากฏระหว่างการดำเนินการ:

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'

คิวรีที่อธิบายได้อย่างสะอาดยังสามารถล้มเหลวเมื่อรันได้ เช่น ข้อจำกัดหน่วยความจำหรือข้อผิดพลาดของเซิร์ฟเวอร์ระยะไกล และไม่ได้บอกอะไรเกี่ยวกับต้นทุน

EXPLAIN ESTIMATE <query> ส่งคืนส่วน แถว และเครื่องหมายที่คิวรีจะอ่าน หนึ่งแถวต่อตาราง ซึ่งเป็นสิ่งที่แยกการค้นหาคีย์หลักจากการสแกนเต็ม:

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

database  table   parts  rows   marks
default   events  1      8192   1

นี่คือการอ่านโดยประมาณจากตารางตระกูล MergeTree หลังจากการตัดคีย์หลักและพาร์ติชัน ไม่ใช่เวลารันและไม่ใช่ขนาดผลลัพธ์ และไม่ครอบคลุมเอ็นจินตารางอื่น

ทั้งสองสเตตเมนต์ไม่รันเนื้อหาคิวรี แต่การวิเคราะห์ไม่ฟรีเสมอไป: DESCRIBE (SELECT (SELECT sleep(1))) ดำเนินการซับคิวรีสเกลาร์ระหว่างการวิเคราะห์ ทั้งสองเป็นแบบอ่านอย่างเดียวและทำงานภายใต้ CLICKHOUSE_ALLOW_WRITE_ACCESS=false ค่าเริ่มต้น ดูเอกสาร ClickHouse สำหรับ EXPLAIN ESTIMATE และ DESCRIBE

เครื่องมือ chDB

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

เอนด์พอยต์ตรวจสอบสุขภาพ

เมื่อรันด้วยการขนส่ง HTTP หรือ SSE เอนด์พอยต์ตรวจสอบสุขภาพจะพร้อมใช้งานที่ /health เอนด์พอยต์นี้:

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

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

ตัวอย่าง:

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

ความปลอดภัย

การรับรองความถูกต้องสำหรับการขนส่ง HTTP/SSE

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

รองรับโหมดการรับรองความถูกต้องสามโหมด เลือกหนึ่งโหมด:

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

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

การตั้งค่าการรับรองความถูกต้อง

  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 ไม่ต้องมีการรับรองความถูกต้องโดยเจตนา (ดู เอนด์พอยต์ตรวจสอบสุขภาพ ด้านบน) เพื่อตรวจสอบว่าการรับรองความถูกต้องแบบแบร์เรอร์โทเค็นปฏิเสธคำขอที่ไม่มีการรับรองความถูกต้องจริง ให้เข้าถึงเอนด์พอยต์ 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>"
export FASTMCP_SERVER_AUTH_AZURE_BASE_URL="https://mcp.example.com"
export FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES="read access_as_user"

mcp-clickhouse เก็บคำนำหน้าสภาพแวดล้อม FastMCP 2.14.7 เหล่านี้สำหรับผู้ให้บริการในตัว FastMCP 4.0.0:

เส้นทางคลาสผู้ให้บริการคำนำหน้าตัวแปรผู้ให้บริการ
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_

ต่อท้ายชื่อฟิลด์ผู้ให้บริการตัวพิมพ์ใหญ่เข้ากับคำนำหน้า ดู เอกสาร FastMCP สำหรับข้อกำหนดการกำหนดค่าของผู้ให้บริการแต่ละราย ค่าการรับรองความถูกต้องที่ตั้งไว้โดยตรงในสภาพแวดล้อมของกระบวนการจะมีความสำคัญสูงกว่าแบบไม่คำนึงถึงตัวพิมพ์ใหญ่-เล็ก การโหลด .env เริ่มต้นจะเริ่มจากไดเรกทอรีแพ็กเกจ mcp_clickhouse ที่ติดตั้งไว้ แก้ไข symlink ก่อน แล้วเดินขึ้นไปจนถึงรากของระบบไฟล์ โดยจะโหลด .env ตัวแรกที่พบ และจะไม่โหลดอะไรเลยหากไม่มีไฟล์ดังกล่าว ระบบจะไม่อ่านไดเรกทอรีทำงาน ไม่ว่าซerverจะถูกเริ่มต้นด้วยวิธีใดก็ตาม การเช็คเอาต์ซอร์สโค้ดโดยปกติจะพบ .env ที่รากของ repository ไฟล์นั้นอาจให้ FASTMCP_SERVER_AUTH และ ฟิลด์ provider ของมันด้วย ค่าของไฟล์นั้นมีความสำคัญสูงกว่าไฟล์การรับรองความถูกต้องแบบชัดเจนหรือแบบเข้ากันได้

สำหรับความเข้ากันได้กับ FastMCP 2 mcp-clickhouse จะอ่านฟิลด์ provider ที่ขาดหายไปจาก .env ในไดเรกทอรีทำงาน แต่การสำรองเพื่อความเข้ากันได้นั้นไม่สามารถเลือก FASTMCP_SERVER_AUTH ได้ FASTMCP_ENV_FILE ที่ตั้งจากกระบวนการจะแทนที่การสำรอง เพื่อความเข้ากันได้นั้น และอาจให้ทั้งฟิลด์ตัวเลือกและ provider ได้ ตั้งค่าก่อนเริ่มต้นระบบ ตัวโหลดเพื่อความเข้ากันได้ของ mcp-clickhouse อ่านเฉพาะ FASTMCP_SERVER_AUTH และ FASTMCP_SERVER_AUTH_* จากไฟล์นั้น ดังนั้นจึงไม่สามารถฉีดการตั้งค่า CLICKHOUSE_* ได้ FastMCP 4 อาจใช้ไฟล์เดียวกันสำหรับการตั้งค่าที่กว้างขึ้นของตัวเอง provider ที่กำหนดเองจะได้รับ ไม่มีอาร์กิวเมนต์ constructor ที่ได้จากสภาพแวดล้อม และต้องรองรับการสร้างแบบไม่มีอาร์กิวเมนต์

ปฏิบัติกับไฟล์ .env ทั้งที่ค้นพบและในไดเรกทอรีทำงานเป็น การกำหนดค่าการรับรองความถูกต้องที่เชื่อถือได้ ใครก็ตามที่สามารถสร้างหรือเขียน .env ในไดเรกทอรีใดก็ได้ตั้งแต่ไดเรกทอรีแพ็กเกจ ขึ้นไปจนถึงรากของระบบไฟล์สามารถควบคุมได้ว่าไฟล์ใดจะถูกค้นพบ เลือก provider และตั้งค่าฟิลด์ของมัน ใครก็ตามที่สามารถเขียนไฟล์ในไดเรกทอรีทำงานได้จะควบคุมทุกฟิลด์ provider ที่ขาดหายไปจากการกำหนดค่าของกระบวนการและที่ค้นพบ รวมถึงคีย์การลงนาม ผู้ออกและ endpoint และความลับของไคลเอ็นต์ FASTMCP_ENV_FILE ที่ตั้งจากกระบวนการซึ่งชี้ ไปยังไฟล์ที่เป็นของโอเปอเรเตอร์จะปิดการสำรองไดเรกทอรีทำงาน

FastMCP 4 เปลี่ยนที่เก็บไคลเอ็นต์พร็อกซี OAuth เริ่มต้น การติดตั้งที่พึ่งพา ที่เก็บพร็อกซี OAuth เริ่มต้นของ FastMCP 2 ต้องให้ไคลเอ็นต์ลงทะเบียนและอนุญาตอีกครั้ง ที่เก็บแบบกำหนดเองที่เข้ากันได้ โทเค็นแบร์เรอร์แบบคงที่ และการตรวจสอบ JWT ไม่ได้รับผลกระทบ

โหมดการพัฒนา (การปิดการรับรองความถูกต้อง)

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

export CLICKHOUSE_MCP_AUTH_DISABLED=true
export CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

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

การกำหนดค่า

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

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

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

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

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

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

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

คุณยังสามารถเปิดใช้งานทั้ง ClickHouse และ 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. ค้นหารายการคำสั่งสำหรับ uv และแทนที่ด้วยพาธสัมบูรณ์ไปยังไฟล์ปฏิบัติการ uv เพื่อให้แน่ใจว่าใช้เวอร์ชันที่ถูกต้องของ uv เมื่อเริ่มต้นเซิร์ฟเวอร์ บน Mac คุณสามารถค้นหาพาธนี้ได้โดยใช้ which uv

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

การเข้าถึงการเขียนแบบไม่บังคับ

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

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

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

แม้เมื่อเปิดใช้งานการเข้าถึงการเขียน (CLICKHOUSE_ALLOW_WRITE_ACCESS=true) การดำเนินการที่ทำลายล้างยังต้องมีแฟล็กการเลือกเข้าร่วมเพิ่มเติมเพื่อความปลอดภัย การตรวจสอบครอบคลุมคำสั่ง DROP ใดๆ (รวมถึงส่วนคำสั่ง ALTER TABLE ... DROP PARTITION / DROP PART / DROP COLUMN) TRUNCATE ใดๆ DELETE และ UPDATE (ทั้งคำสั่งแบบเบาและการกลายพันธุ์ ALTER TABLE ... DELETE / ALTER TABLE ... UPDATE) REPLACE TABLE CREATE OR REPLACE ALTER TABLE ... REPLACE PARTITION ALTER TABLE ... CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION และ DETACH ... PERMANENTLY คำสำคัญภายในสตริงลิเทอรัล ตัวระบุที่อ้างอิง ความคิดเห็น SQL และชื่อพารามิเตอร์ {name:Type} จะถูกละเว้น ดังนั้นจึงไม่ทำให้เกิดการตรวจสอบหรือซ่อนคำสั่งจากการตรวจสอบ

การตรวจสอบนี้ทำงานใน MCP เซิร์ฟเวอร์และเป็นการป้องกันความผิดพลาดที่ดีที่สุด ไม่ใช่ขอบเขตความปลอดภัย ขอบเขตความปลอดภัยคือสิทธิ์ที่ได้รับของผู้ใช้ ClickHouse โหมดอ่านอย่างเดียว (ค่าเริ่มต้น) ถูกบังคับใช้ฝั่งเซิร์ฟเวอร์ผ่าน readonly=1 เกตการดำเนินการที่ทำลายล้างไม่ได้ถูกบังคับใช้ฝั่งเซิร์ฟเวอร์

สำหรับโหมดเขียน ให้ MCP เซิร์ฟเวอร์มีผู้ใช้ ClickHouse เฉพาะที่มีสิทธิ์เท่าที่จำเป็นเท่านั้น:

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

การดำเนินการที่เปลี่ยนแปลงข้อมูลซึ่งต้องใช้สิทธิ์นอกเหนือจากสิทธิ์เหล่านี้จะล้มเหลวฝั่งเซิร์ฟเวอร์ด้วย ACCESS_DENIED โดยไม่คำนึงถึงแฟล็ก MCP การตั้งค่าเซิร์ฟเวอร์ max_table_size_to_drop และ max_partition_size_to_drop ยังสามารถจำกัดขอบเขตความเสียหายได้หากถูกตรึงด้วยข้อจำกัดการตั้งค่า

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

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

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

  • การดำเนินการเขียน (INSERT, CREATE, ALTER ADD COLUMN) ต้องใช้ CLICKHOUSE_ALLOW_WRITE_ACCESS=true
  • การดำเนินการที่ทำลายล้าง (DROP, TRUNCATE, DELETE, UPDATE และรายการอื่นๆ ข้างต้น) ต้องใช้ CLICKHOUSE_ALLOW_DROP=true เพิ่มเติม

การรันโดยไม่ใช้ uv (ใช้ 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"
      }
    }
  }
}

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

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

หมายเหตุ: ตรวจสอบให้แน่ใจว่าใช้พาธเต็มไปยังไฟล์ปฏิบัติการ 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.12", "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 มีฮุคสำหรับการดำเนินการ MCP ต่างๆ:

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

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

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

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

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)

这使得可以实现高级用例 เช่น การปรับเวลาหมดเวลาแบบไดนามิก การกำหนดเส้นทางตามผู้เช่า หรือการตั้งค่าการเชื่อมต่อตามผู้ใช้

ค่าของ state ต้องเป็น dictionary ค่า settings และ generic_args ที่ซ้อนกันต้องเป็น mapping และจะถูกรวมกับการกำหนดค่าพื้นฐาน ค่าที่ไม่ถูกต้องจะทำให้การเรียกเครื่องมือล้มเหลวก่อน ที่ไคลเอ็นต์ ClickHouse จะถูกสร้าง CLICKHOUSE_ROLE ยังคงทำงานอยู่เว้นแต่การแทนที่จะระบุ settings.role อย่างชัดเจน คีย์ระดับบนสุด role และ ch_role รวมถึงคีย์เดียวกันภายใต้ generic_args จะถูกปฏิเสธ

ตั้งค่า verify, ca_cert, client_cert, client_cert_key, tls_mode, server_host_name, และ pool_mgr เป็นการแทนที่ระดับบนสุดเท่านั้น ไม่สามารถซ้อนภายใต้ generic_args ได้ pool_mgr แบบกำหนดเองไม่สามารถรวมกับการจัดการ CA หรือการตั้งค่าใบรับรองไคลเอ็นต์ได้ พารามิเตอร์คิวรี DSN ไม่สามารถตั้งค่าคีย์เหล่านี้ได้ และ DSN ไม่สามารถเลือกแบ็กเอนด์ chdb ได้ ใช้ การแทนที่ระดับบนสุดที่ชัดเจน host, port, username, password, database และ secure เพื่อเปลี่ยน การเชื่อมต่อ DSN ที่ส่งต่อไม่ได้แทนที่ฟิลด์การเชื่อมต่อพื้นฐานที่เติมแล้วหรือเลือก TLS สามารถเติมฟิลด์ว่างและให้พารามิเตอร์คิวรีที่รองรับ เช่น query_limit การแทนที่ secure และ verify ยอมรับบูลีนหรือสตริง true และ false verify ยังยอมรับ proxy ซึ่งทำงานเป็น tls_mode: proxy เมื่อ tls_mode ไม่ได้ตั้งค่า และจึงใช้การรับรองความถูกต้องแบบ Basic กับ รหัสผ่านจากสภาพแวดล้อม การแทนที่ secure เลือกอินเทอร์เฟซ https หรือ http ที่ตรงกันและ ไม่เปลี่ยนพอร์ต การแทนที่ interface ที่ชัดเจนต้องเป็น http หรือ https และสอดคล้อง กับ secure หลังจากการรวมการแทนที่ โหมดใบรับรองไคลเอ็นต์เริ่มต้นและ mutual จะละเว้น รหัสผ่าน โหมด proxy และ strict ใช้การรับรองความถูกต้องแบบ Basic กับรหัสผ่านจากสภาพแวดล้อม เว้นแต่การแทนที่จะให้ข้อมูลประจำตัวของตัวเอง

ปฏิบัติต่อการแทนที่เหล่านี้เป็นอินพุตมิดเดิลแวร์ที่เชื่อถือได้ มิดเดิลแวร์ต้องรับรองความถูกต้องและอนุญาต ค่าที่ได้จากคำขอก่อนตั้งค่า ใช้ serializable=False เพื่อให้ FastMCP เก็บ ค่าใน state เฉพาะคำขอ serializable=True เริ่มต้นจะเก็บ state ของเซสชันและ ถูกปฏิเสธโดยเซิร์ฟเวอร์ เซิร์ฟเวอร์จะสแนปช็อตค่าก่อนส่งงานฐานข้อมูลแบบบล็อก อย่าเก็บข้อมูลผู้เช่าใน Context state ระดับเซสชัน การแทนที่ระดับเซสชันที่ถูกปฏิเสธ ยังคงติดอยู่กับเซสชัน MCP แบบเดิมและทำให้การเรียกเครื่องมือในภายหลังในเซสชันนั้น ล้มเหลวจนกว่าไคลเอ็นต์จะเชื่อมต่อใหม่ บทบาท ClickHouse ต่อคำขอเป็นการกำหนดค่าการเชื่อมต่อ ไม่ใช่ขอบเขตการอนุญาตผู้เช่า บังคับใช้การแยกผู้เช่าด้วยผู้ใช้ บทบาท และสิทธิ์ของ ClickHouse

การพัฒนา

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

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

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

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

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

  2. เพื่อการทดสอบที่ง่ายด้วย MCP Inspector ให้รัน uv run fastmcp dev inspector mcp_clickhouse/mcp_server.py:mcp เพื่อเริ่ม MCP server

  3. เพื่อทดสอบกับ HTTP transport และ health check endpoint:

    # 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

โครงสร้างโค้ด

แพ็กเกจใช้โครงสร้างโมดูลแบบเรียบ เริ่มจาก mcp_server.py สำหรับการประกอบและลงทะเบียนเซิร์ฟเวอร์ จากนั้นติดตามการใช้งานไปยังโมดูลที่เป็นเจ้าของ

โมดูลความรับผิดชอบ
mcp_server.py, main.pyการประกอบเริ่มต้น, การลงทะเบียนเครื่องมือและพรอมต์, การประสานงานการปิดระบบ, และการเริ่มต้น CLI
clients.pyการกำหนดค่าคำขอ, การเชื่อมต่อ ClickHouse ที่แคชไว้, และการเช่าลูกค้า
queries.pyการดำเนินการคิวรี, การยกเลิก, และการป้องกันการดำเนินการที่ทำลายข้อมูล
metadata.pyการค้นพบฐานข้อมูลและตาราง, โมเดล metadata, และการแบ่งหน้า
chdb_backend.py, chdb_prompt.pyการเริ่มต้น chDB แบบไม่บังคับ, การดำเนินการคิวรี, และเนื้อหาพรอมต์
health.py, executors.pyการตรวจสอบสุขภาพและการแคช, และพูล worker ที่ใช้ในการดำเนินการของเซิร์ฟเวอร์
auth.py, transport.py, http_security.pyการโหลด Dotenv, การรับรองความถูกต้อง, การสร้างแอป HTTP/SSE, และการตรวจสอบ Host/Origin
mcp_env.py, serialization.pyการกำหนดค่าสภาพแวดล้อมและการเข้ารหัสผลลัพธ์ JSON
mcp_middleware_hook.py, skills_advisor.pyการโหลด middleware ที่กำหนดเองและคำแนะนำเซิร์ฟเวอร์

การประกอบเซิร์ฟเวอร์แต่ละตัวเป็นเจ้าของพูล worker, แคชลูกค้า, คิวรีที่ใช้งานอยู่, แคชการแบ่งหน้า, สถานะสุขภาพ, และแบ็กเอนด์ chDB การทำความสะอาด worker และลูกค้าจะทำงานเมื่อออกจากกระบวนการ การนำเข้าแพ็กเกจจะเริ่มต้นเซิร์ฟเวอร์เริ่มต้น รวมถึงเมื่อนำเข้าโมดูลที่แยกออกมาเป็นครั้งแรก

ในการทดสอบ ให้แพตช์โมดูลหรืออินสแตนซ์เจ้าของที่โค้ดอ่าน dependency ตัวอย่างเช่น แพตช์ mcp_clickhouse.clients.clickhouse_connect.get_client สำหรับการสร้างลูกค้า การนำเข้าเพื่อความเข้ากันได้ใน mcp_server.py อาจเป็นการผูกที่แยกจากการผูกที่การใช้งานใช้

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

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

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

[!IMPORTANT] CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, CLICKHOUSE_CA_CERT, CLICKHOUSE_CLIENT_CERT, CLICKHOUSE_CLIENT_CERT_KEY, CLICKHOUSE_TLS_MODE, และ CLICKHOUSE_PORT ใช้กับการเชื่อมต่อ ฐานข้อมูล ClickHouse ขาออกเท่านั้น ไม่ได้กำหนดค่า TLS, ใบรับรองลูกค้า, พอร์ต, หรือการรับรองความถูกต้องสำหรับ endpoint MCP HTTP/SSE ขาเข้า

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

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

ตัวแปรเหล่านี้กำหนดค่า HTTP client ของ clickhouse-connect และพฤติกรรมของเครื่องมือที่ใช้ ClickHouse เช่น run_query, list_databases, และ list_tables mcp-clickhouse ต้องใช้ clickhouse-connect 1.x เริ่มจาก 1.0.0

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

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

ตัวแปรที่ไม่บังคับ
  • CLICKHOUSE_PORT: พอร์ต HTTP interface ของเซิร์ฟเวอร์ ClickHouse ของคุณ
    • ค่าเริ่มต้น: 8443 หาก CLICKHOUSE_SECURE=true, 8123 หาก CLICKHOUSE_SECURE=false
    • โดยปกติไม่จำเป็นต้องตั้งค่าเว้นแต่ใช้พอร์ตที่ไม่ได้มาตรฐาน
    • ต้องเป็นพอร์ต HTTP interface ไม่ใช่พอร์ตโปรโตคอล TCP ดั้งเดิมที่ใช้โดย clickhouse-client
    • ค่าทั่วไป:
      • HTTP: 8123 (plain) / 8443 (TLS) — ใช้โดยเซิร์ฟเวอร์นี้และ ClickHouse Cloud HTTPS
      • Native TCP (ไม่รองรับที่นี่): 9000 (plain) / 9440 (TLS) — ใช้โดย clickhouse-client
    • หากเซิร์ฟเวอร์ตอบสนองด้วย Port 9000 is for clickhouse-client program แสดงว่าคุณชี้ไปที่โปรโตคอลดั้งเดิม ให้สลับไปที่พอร์ต HTTP (8123/8443 หรือการแมป HTTP ของการปรับใช้ของคุณ)
  • CLICKHOUSE_ROLE: บทบาท ClickHouse ที่ใช้สำหรับการรับรองความถูกต้อง
    • ค่าเริ่มต้น: None
    • ตั้งค่านี้หากผู้ใช้ของคุณต้องการบทบาทเฉพาะ
  • CLICKHOUSE_SECURE: เปิดใช้งาน HTTPS สำหรับการเชื่อมต่อฐานข้อมูล ClickHouse (ไม่ใช่สำหรับลูกค้า MCP)
    • ค่าเริ่มต้น: "true"
    • ตั้งค่าเป็น "false" เฉพาะเมื่อ MCP server เข้าถึง ClickHouse ผ่าน plain HTTP (โดยทั่วไปสำหรับ Docker Compose ในเครื่องบนพอร์ต 8123)
    • ปล่อย "true" สำหรับ ClickHouse Cloud และ endpoint ฐานข้อมูล HTTPS ใดๆ—แม้ว่า MCP server เองจะถูกเปิดเผยผ่าน HTTP, stdio, หรือ ingress ที่ยุติ TLS แยกต่างหาก
    • การไม่ตรงกันของแฟล็กนี้กับพอร์ตฐานข้อมูล (เช่น CLICKHOUSE_SECURE=false กับพอร์ต 8443) เป็นข้อผิดพลาดในการตั้งค่าที่พบบ่อย และมักปรากฏเป็นข้อผิดพลาด HTTP client ที่สับสนมากกว่าข้อความ "wrong scheme" ที่ชัดเจน
  • CLICKHOUSE_VERIFY: เปิด/ปิดการตรวจสอบใบรับรอง SSL สำหรับการเชื่อมต่อ HTTPS ClickHouse
    • ค่าเริ่มต้น: "true"
    • ตั้งค่าเป็น "false" เพื่อปิดการตรวจสอบใบรับรอง (ไม่แนะนำสำหรับการผลิต)
    • ใบรับรอง TLS: แพ็กเกจใช้ trust store ของระบบปฏิบัติการของคุณผ่าน truststore.inject_into_ssl() เมื่อเริ่มต้น การจัดการ SSL เริ่มต้นของ Python จะใช้หากการฉีดถูกปิดด้วย MCP_CLICKHOUSE_TRUSTSTORE_DISABLE=1 หรือล้มเหลว
  • MCP_CLICKHOUSE_TRUSTSTORE_DISABLE: ปิดการรวม trust store ของระบบปฏิบัติการทั้งกระบวนการสำหรับ TLS
    • ค่าเริ่มต้น: ไม่ได้ตั้งค่า (เปิดใช้งานการรวม trust store)
    • ตั้งค่าเป็น "1" ก่อนเริ่มต้นเพื่อข้าม truststore.inject_into_ssl() และใช้การจัดการใบรับรอง SSL เริ่มต้นของ Python ค่าอื่นไม่ปิดการรวม
    • สิ่งนี้ไม่ได้ปิดการตรวจสอบใบรับรอง CLICKHOUSE_VERIFY ยังคงควบคุมการตรวจสอบสำหรับการเชื่อมต่อ HTTPS ClickHouse
  • CLICKHOUSE_CA_CERT: เส้นทางไปยังชุดใบรับรอง CA แบบ PEM สำหรับการเชื่อมต่อ HTTPS ClickHouse
    • ค่าเริ่มต้น: None (ใช้ trust store ของระบบปฏิบัติการเว้นแต่การฉีด truststore ถูกปิดหรือล้มเหลว)
    • ใช้ค่านี้เพียงอย่างเดียวเมื่อเซิร์ฟเวอร์ ClickHouse หรือพร็อกซีส่วนตัวแสดงใบรับรองที่ลงนามโดย CA ส่วนตัว สิ่งนี้เปลี่ยนการตรวจสอบใบรับรองเซิร์ฟเวอร์และไม่เปิดใช้งานการรับรองความถูกต้องด้วยใบรับรองลูกค้า
    • ต้องใช้ CLICKHOUSE_SECURE=true และ CLICKHOUSE_VERIFY=true
  • CLICKHOUSE_CLIENT_CERT: เส้นทางไปยังใบรับรองลูกค้าแบบ PEM สำหรับการเชื่อมต่อ HTTPS ClickHouse
    • ค่าเริ่มต้น: None
    • ไฟล์อาจมีคีย์ส่วนตัวด้วย มิฉะนั้นให้ตั้งค่า CLICKHOUSE_CLIENT_CERT_KEY
    • ผู้ใช้ ClickHouse ยังคงมาจาก CLICKHOUSE_USER
  • CLICKHOUSE_CLIENT_CERT_KEY: เส้นทางไปยังคีย์ส่วนตัวแบบ PEM สำหรับ CLICKHOUSE_CLIENT_CERT
    • ค่าเริ่มต้น: None
    • ไม่บังคับเมื่อคีย์ส่วนตัวรวมอยู่ในไฟล์ใบรับรองลูกค้า
    • ไม่สามารถใช้ได้หากไม่มี CLICKHOUSE_CLIENT_CERT
  • CLICKHOUSE_TLS_MODE: วิธีที่ clickhouse-connect ใช้ CLICKHOUSE_CLIENT_CERT
    • ค่าเริ่มต้น: None ซึ่งทำงานเป็น "mutual" เมื่อตั้งค่าใบรับรองลูกค้า
    • "mutual": ใช้ใบรับรองลูกค้าสำหรับการรับรองความถูกต้องผู้ใช้ X.509 ของ ClickHouse CLICKHOUSE_PASSWORD ไม่บังคับและไม่ถูกส่ง
    • "proxy": นำเสนอใบรับรองลูกค้าให้กับพร็อกซีที่ยุติ TLS จากนั้นใช้การรับรองความถูกต้อง Basic ของ ClickHouse ต้องใช้ CLICKHOUSE_PASSWORD
    • "strict": นำเสนอใบรับรองลูกค้าเพราะเซิร์ฟเวอร์ ClickHouse ต้องการที่ชั้น TLS จากนั้นใช้การรับรองความถูกต้อง Basic ของ ClickHouse ต้องใช้ CLICKHOUSE_PASSWORD โหมดนี้ไม่ได้เสริมการตรวจสอบใบรับรองเซิร์ฟเวอร์ CLICKHOUSE_VERIFY ควบคุมการตรวจสอบนั้น
    • clickhouse-connect ปฏิบัติต่อ "proxy" และ "strict" เหมือนกัน สองชื่อนี้บันทึกเจตนา
    • ค่าจะถูกตัดและไม่คำนึงถึงตัวพิมพ์เล็กใหญ่ ค่าว่างถือเป็นไม่ได้ตั้งค่า ค่าอื่นจะถูกปฏิเสธก่อนสร้างลูกค้า ClickHouse ในการเรียกเครื่องมือ ClickHouse ครั้งแรกหรือการตรวจสอบ /health
    • ต้องใช้ CLICKHOUSE_CLIENT_CERT ตัวเลือกใบรับรองลูกค้าทั้งหมดต้องใช้ CLICKHOUSE_SECURE=true
  • CLICKHOUSE_SERVER_HOST_NAME: ชื่อโฮสต์เซิร์ฟเวอร์สำหรับการแทนที่ SNI และการตรวจสอบใบรับรองในการเชื่อมต่อ ClickHouse
    • ค่าเริ่มต้น: None (ใช้ชื่อโฮสต์การเชื่อมต่อ)
    • มีประโยชน์เมื่อเชื่อมต่อผ่านพร็อกซีหรือตัวโหลดบาลานซ์ที่ชื่อโฮสต์ใบรับรองแตกต่างจากชื่อโฮสต์การเชื่อมต่อ เมื่อตั้งค่า ชื่อโฮสต์นี้จะใช้สำหรับทั้ง SNI (Server Name Indication) ระหว่างการจับมือ TLS และการตรวจสอบชื่อโฮสต์ใบรับรอง
  • CLICKHOUSE_PROXY_PATH: คำนำหน้าเส้นทาง URL สำหรับ endpoint HTTP ของ ClickHouse
    • ค่าเริ่มต้น: None
    • ตั้งค่านี้เมื่อ HTTP interface ของ ClickHouse ถูกเปิดเผยหลัง reverse proxy ภายใต้คำนำหน้าเส้นทาง (ตัวอย่างเช่น /clickhouse)
  • CLICKHOUSE_CONNECT_TIMEOUT: หมดเวลาการเชื่อมต่อเป็นวินาทีสำหรับลูกค้า ClickHouse
    • ค่าเริ่มต้น: "30"
    • เพิ่มค่านี้หากคุณพบการหมดเวลาการเชื่อมต่อ
  • CLICKHOUSE_SEND_RECEIVE_TIMEOUT: หมดเวลาการส่ง/รับเป็นวินาทีสำหรับลูกค้า ClickHouse
    • ค่าเริ่มต้น: ค่าที่ต่ำกว่าของ 300 หรือ CLICKHOUSE_MCP_QUERY_TIMEOUT + 5 เพื่อให้เธรด worker ปลดบล็อกไม่นานหลังจากการหมดเวลาคิวรี
    • หากตั้งค่าอย่างชัดเจน ค่าจะถูกใช้ตามที่เป็น (เช่น "300" สำหรับคิวรีที่รันนาน)
  • CLICKHOUSE_DATABASE: ฐานข้อมูล ClickHouse เริ่มต้นที่จะใช้
    • ค่าเริ่มต้น: None (ใช้ค่าเริ่มต้นของเซิร์ฟเวอร์)
    • ตั้งค่านี้เพื่อเชื่อมต่อกับฐานข้อมูลเฉพาะโดยอัตโนมัติ
  • CLICKHOUSE_ENABLED: เปิด/ปิดเครื่องมือฐานข้อมูล ClickHouse
    • ค่าเริ่มต้น: "true"
    • ตั้งค่าเป็น "false" เพื่อปิดเครื่องมือ ClickHouse เมื่อใช้ chDB เท่านั้น
  • CLICKHOUSE_ALLOW_WRITE_ACCESS: อนุญาตการดำเนินการเขียน (DDL และ DML) กับ ClickHouse
    • ค่าเริ่มต้น: "false"
    • ตั้งค่าเป็น "true" เพื่ออนุญาต DDL และ DML ที่ไม่ทำลาย (CREATE, INSERT, ALTER ADD COLUMN) คำสั่งที่ทำลายเพิ่มเติมต้องใช้ CLICKHOUSE_ALLOW_DROP=true
    • เมื่อปิด (ค่าเริ่มต้น) คิวรีจะรันด้วยการตั้งค่า readonly=1 เพื่อป้องกันการแก้ไขข้อมูล
  • CLICKHOUSE_ALLOW_DROP: อนุญาตการดำเนินการที่ทำลาย (ใดๆ DROP หรือ TRUNCATE, DELETE และ UPDATE รวมถึงตัวแปร ALTER TABLE, REPLACE TABLE / REPLACE PARTITION / CREATE OR REPLACE, CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION, และ DETACH ... PERMANENTLY)
    • ค่าเริ่มต้น: "false"
    • มีผลเฉพาะเมื่อตั้งค่า CLICKHOUSE_ALLOW_WRITE_ACCESS=true ด้วย
    • เกตนี้เป็นการป้องกันอุบัติเหตุแบบ best-effort ใน MCP server ไม่ใช่ขอบเขตความปลอดภัย จำกัดสิทธิ์ของผู้ใช้ ClickHouse สำหรับการบังคับใช้จริง (ดู Destructive Operation Protection)
ไฟล์ใบรับรอง TLS ของ ClickHouse

ตัวแปรใบรับรองประกอบด้วยเส้นทางของไฟล์ ไม่ใช่เนื้อหา PEM mcp-clickhouse จะส่งเส้นทางเหล่านี้ไปยัง clickhouse-connect สำหรับ Docker หรือ Kubernetes ให้เมานต์ใบรับรองและคีย์ส่วนตัวเป็นไฟล์แบบอ่านอย่างเดียว และใช้เส้นทางภายในคอนเทนเนอร์ อย่าใส่คีย์ส่วนตัวลงในอิมเมจ คอมมิตลงในระบบควบคุมเวอร์ชัน หรือใส่เนื้อหาลงในตัวแปรสภาพแวดล้อม

ในโหมด mutual ใบรับรองไคลเอ็นต์ที่กำหนดค่าจะระบุตัวตนของกระบวนการ mcp-clickhouse นี้เป็น CLICKHOUSE_USER โดยไม่มีการตรวจสอบสิทธิ์ไคลเอ็นต์ MCP ที่เข้ามาหรือส่งต่อข้อมูลประจำตัวไปยัง ClickHouse กำหนดค่าการตรวจสอบสิทธิ์การขนส่ง MCP แยกต่างหาก

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

ClickHouse Cloud ไม่รองรับการตรวจสอบสิทธิ์ใบรับรองไคลเอ็นต์ X.509 สำหรับผู้ใช้ฐานข้อมูล ใช้ CLICKHOUSE_USER และ CLICKHOUSE_PASSWORD สำหรับ ClickHouse Cloud ใบรับรอง CA ยังคงมีประโยชน์เมื่อพร็อกซีส่วนตัวที่อยู่หน้าปลายทางนำเสนอใบรับรองที่ลงนามโดย CA ส่วนตัว

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

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

  • CLICKHOUSE_MCP_SERVER_TRANSPORT: กำหนดวิธีการขนส่งสำหรับเซิร์ฟเวอร์ MCP
    • ค่าเริ่มต้น: "stdio"
    • ตัวเลือกที่ถูกต้อง: "stdio", "http", "sse" มีประโยชน์สำหรับการพัฒนาท้องถิ่นด้วยเครื่องมือเช่น MCP Inspector
    • stdio เป็นเรื่องปกติสำหรับ Claude Desktop; http/sse เปิดเผยตัวฟังเครือข่าย (ผูกโฮสต์/พอร์ตด้านล่าง)
    • "sse" เลือกการขนส่ง HTTP+SSE แบบสแตนด์อโลนที่เลิกใช้แล้วและบันทึกคำเตือน ใช้ "http" สำหรับ Streamable HTTP ในการปรับใช้ใหม่
  • 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 ... สำหรับคิวรีที่หนัก
    • เมื่อคิวรีหมดเวลา เซิร์ฟเวอร์จะพยายามยกเลิกด้วย KILL QUERY
    • เว้นแต่ CLICKHOUSE_SEND_RECEIVE_TIMEOUT จะถูกตั้งอย่างชัดเจน หมดเวลาการอ่าน HTTP จะถูกจำกัดที่ค่านี้บวกห้าวินาที
  • CLICKHOUSE_MCP_MAX_WORKERS: จำนวนสูงสุดของเธรดผู้ปฏิบัติงานคิวรีพร้อมกัน
    • ค่าเริ่มต้น: "10"
    • เพิ่มหากปริมาณงานของคุณต้องการการเรียกเครื่องมือพร้อมกันจำนวนมาก
    • เครื่องมือเมตาดาต้าใช้พูลแยกต่างหากด้วยเธรด min(4, CLICKHOUSE_MCP_MAX_WORKERS) เพื่อให้การค้นพบสคีมาไม่ทำให้คิวรีล่าช้า
  • CLICKHOUSE_MCP_AUTH_TOKEN: โทเค็นแบร์เรอร์แบบคงที่สำหรับการขนส่ง 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
    • เมื่อตั้งค่า mcp-clickhouse จะโหลดผู้ให้บริการจากตัวแปรสภาพแวดล้อม FASTMCP_SERVER_AUTH_* ที่มีอยู่; ปล่อย CLICKHOUSE_MCP_AUTH_TOKEN ไม่ได้ตั้งในโหมดนี้
    • ผู้ให้บริการที่กำหนดเองไม่ได้รับอาร์กิวเมนต์ตัวสร้างที่มาจากสภาพแวดล้อมและต้องรองรับการสร้างโดยไม่มีอาร์กิวเมนต์
    • FastMCP 4 ไม่รองรับการตรวจสอบ HS256 ของ Supabase อีกต่อไป การปรับใช้ Supabase ต้องใช้ RS256 หรือ ES256
  • FASTMCP_ENV_FILE: ไฟล์ทางเลือกที่มี FASTMCP_SERVER_AUTH และตัวแปรสภาพแวดล้อมเฉพาะผู้ให้บริการ
    • ค่าเริ่มต้น: ไม่มี เมื่อไม่ได้ตั้ง ตัวโหลดความเข้ากันได้จะอ่านฟิลด์ผู้ให้บริการที่ขาดหายไปจาก .env ในไดเรกทอรีทำงาน ไม่ได้อ่าน FASTMCP_SERVER_AUTH จากตัวสำรองนั้น
    • ตั้งในสภาพแวดล้อมกระบวนการก่อนเริ่มต้น ค่าที่โหลดจาก .env เริ่มต้นไม่สามารถเปลี่ยนเส้นทางตัวโหลดความเข้ากันได้
    • หากตั้งโดยกระบวนการ ไฟล์นี้อาจให้ทั้ง FASTMCP_SERVER_AUTH และฟิลด์ผู้ให้บริการ และแทนที่ตัวสำรองไดเรกทอรีทำงาน
    • ค่าสภาพแวดล้อมกระบวนการมีลำดับความสำคัญโดยไม่คำนึงถึงตัวพิมพ์เล็กใหญ่
    • ตัวโหลดความเข้ากันได้ของ mcp-clickhouse อ่านไฟล์นี้เฉพาะเมื่อสร้างการตรวจสอบสิทธิ์ HTTP/SSE และอ่านเฉพาะรายการ FASTMCP_SERVER_AUTH และ FASTMCP_SERVER_AUTH_* FastMCP 4 อาจอ่านไฟล์เดียวกันสำหรับการตั้งค่าที่กว้างขึ้น
    • การโหลด .env เริ่มต้นแยกต่างหาก เริ่มต้นที่ไดเรกทอรีแพ็กเกจ mcp_clickhouse ที่ติดตั้ง แก้ลิงก์สัญลักษณ์ เดินขึ้นไปยังรากระบบไฟล์ และโหลด .env แรกที่พบหรือไม่มีเลย ไม่เคยอ่านไดเรกทอรีทำงาน ไม่ว่าวิธีการเริ่มต้นใด ไฟล์นั้นอาจให้ FASTMCP_SERVER_AUTH และฟิลด์ผู้ให้บริการพร้อมกับการตั้งค่าเซิร์ฟเวอร์อื่น การเช็คเอาต์ซอร์สโดยปกติจะพบ .env ที่รากของที่เก็บ
  • CLICKHOUSE_MCP_AUTH_DISABLED: ปิดการตรวจสอบสิทธิ์สำหรับการขนส่ง HTTP/SSE
    • ค่าเริ่มต้น: "false" (เปิดการตรวจสอบสิทธิ์)
    • ตั้งเป็น "true" เพื่อปิดการตรวจสอบสิทธิ์สำหรับการพัฒนาท้องถิ่น/การทดสอบเท่านั้น
    • คำเตือน: ใช้สำหรับการพัฒนาท้องถิ่นเท่านั้น อย่าปิดเมื่อเปิดเผยต่อเครือข่าย
  • CLICKHOUSE_MCP_ALLOWED_HOSTS: ค่าที่คั่นด้วยเครื่องหมายจุลภาคของส่วนหัว Host ที่เซิร์ฟเวอร์ HTTP/SSE ตอบสนอง
    • ค่าเริ่มต้นสำหรับการผูก loopback: รูปแบบเปล่าและพอร์ตใดก็ได้ของ 127.0.0.1, localhost, และ [::1]
    • หากตั้ง ค่าต้องมีรายการ Host อย่างน้อยหนึ่งรายการ
    • ที่อยู่ผูกที่ไม่ใช่ loopback ที่เป็นรูปธรรมเริ่มต้นที่ที่อยู่นั้นและพอร์ตที่กำหนดค่า การผูกแบบไวด์การ์ดเช่น 0.0.0.0 หรือ :: ต้องมีค่าที่ไม่ว่างอย่างชัดเจนเพราะไม่สามารถอนุมาน Host สาธารณะได้
    • การตรวจสอบ Host เป็นการป้องกันเชิงลึกต่อ DNS rebinding การตรวจสอบ Origin ด้านล่างจำเป็นแยกต่างหากโดย MCP
    • รายการเป็นแบบตรง (localhost:8000) หรือยอมรับพอร์ตใดก็ได้ (localhost:*) ตัวอย่าง: CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000
    • รูปแบบ host:* ตรงกับค่าที่มีพอร์ตเท่านั้น Host ที่ไม่มีพอร์ต (การปรับใช้พอร์ตมาตรฐานที่ไคลเอ็นต์ละเว้น :80/:443) ต้องระบุเป็นรายการตรงเปล่า (example.com) ด้วย
    • คำขอที่มีส่วนหัว Host ที่ไม่ตรงหรือขาดหายไปจะได้รับ 421 Misdirected Request คำขอ GET และ HEAD ไปยัง /health ได้รับการยกเว้นจากการตรวจสอบ Host และ Origin เพื่อให้พร็อบของออร์เคสเตรเตอร์ทำงานต่อไป
    • หลังพร็อกซีย้อนกลับ ควรเก็บส่วนหัว Host เดิมไว้ คุณสามารถระบุค่าต้นทาง Host ที่พร็อกซีส่งแทน ตั้งรายการที่ชัดเจนเมื่อตัวเรียกใช้เช่น fastmcp run เปลี่ยนที่อยู่ผูกสำหรับการเข้าถึงระยะไกล
    • mcp-clickhouse บังคับปิดการ์ด Host และ Origin แยกของ FastMCP FASTMCP_HTTP_HOST_ORIGIN_PROTECTION, FASTMCP_HTTP_ALLOWED_HOSTS, และ FASTMCP_HTTP_ALLOWED_ORIGINS ไม่มีผล CLICKHOUSE_MCP_ALLOWED_HOSTS และ CLICKHOUSE_MCP_ALLOWED_ORIGINS มีอำนาจ
  • CLICKHOUSE_MCP_TRUSTED_PROXIES: ที่อยู่ IP พร็อกซีหรือเครือข่าย CIDR ที่เชื่อถือส่วนหัว X-Forwarded-*
    • ค่าเริ่มต้น: ไม่มี X-Forwarded-Host ถูกละเว้น การจัดการ Uvicorn ที่มีอยู่ของ X-Forwarded-For และ X-Forwarded-Proto ไม่เปลี่ยนแปลง
    • รายการต้องเป็นที่อยู่ IP หรือเครือข่าย CIDR เช่น 127.0.0.1,10.20.0.0/24,2001:db8::1 CIDR ต้องใช้ที่อยู่เครือข่าย ดังนั้น 10.20.0.1/24 ถูกปฏิเสธ ชื่อโฮสต์ ที่อยู่ IPv6 แบบมีขอบเขต *, 0.0.0.0/0, และ ::/0 ถูกปฏิเสธเช่นกัน
    • ความเชื่อถือขึ้นอยู่กับเพียร์ซ็อกเก็ตดิบทันที คำขอจากเพียร์อื่น หรือคำขอที่ไม่มีที่อยู่ไคลเอ็นต์ จะละเว้น X-Forwarded-Host และตรวจสอบ Host
    • เพียร์ที่เชื่อถืออาจส่งส่วนหัว X-Forwarded-Host หนึ่งรายการที่มีค่าที่ไม่ว่างหนึ่งค่า ฟิลด์ซ้ำ ค่าว่าง และรายการที่คั่นด้วยเครื่องหมายจุลภาคจะได้รับ 421 Misdirected Request หากไม่มีส่วนหัว Host จะถูกตรวจสอบ
    • ใช้ที่อยู่หรือเครือข่ายที่แคบที่สุดเท่าที่เป็นไปได้ เซิร์ฟเวอร์ MCP ต้องเข้าถึงได้ผ่านพร็อกซีในช่วงที่กำหนดค่าเท่านั้น พร็อกซีที่เชื่อถือทุกตัวต้องลบและเขียนทับค่า X-Forwarded-Host และ X-Forwarded-Proto ที่ไคลเอ็นต์ส่ง และสร้าง X-Forwarded-For จากเพียร์การเชื่อมต่อที่ตรวจสอบแล้ว
    • เซิร์ฟเวอร์ในตัวและ fastmcp run ปิดการจัดการส่วนหัวพร็อกซีภายนอกของ Uvicorn ตรวจสอบ Host จากเพียร์ดิบ จากนั้นใช้ X-Forwarded-For และ X-Forwarded-Proto การเปิด uvicorn_config["proxy_headers"] อย่างชัดเจนทำให้การเริ่มต้นล้มเหลวในโหมดนี้
    • การฝัง ASGI โดยตรงต้องปิดการจัดการส่วนหัวพร็อกซีในเซิร์ฟเวอร์ ASGI ภายนอกและเรียก mcp.http_app(raw_client_address_preserved=True) หากไม่มีการยืนยันที่ชัดเจนนั้น การสร้างแอปจะล้มเหลวเมื่อกำหนดค่าพร็อกซีที่เชื่อถือ
  • CLICKHOUSE_MCP_ALLOWED_ORIGINS: ค่าที่คั่นด้วยเครื่องหมายจุลภาคของส่วนหัว Origin ที่ยอมรับบน HTTP/SSE
    • ค่าเริ่มต้น: ไม่มี ซึ่งปฏิเสธทุกคำขอที่มีส่วนหัว Origin
    • MCP ต้องการการตรวจสอบ Origin สำหรับการเชื่อมต่อการขนส่ง HTTP/SSE คำขอที่ไม่มี Origin จะถูกยอมรับเพราะไคลเอ็นต์ MCP ที่ไม่ใช่เบราว์เซอร์มักละเว้น Origin ที่ไม่ตรงจะได้รับ 403 Forbidden ปลายทาง /health ได้รับการยกเว้นตามที่อธิบายข้างต้น
    • รายการเป็นแบบตรง (http://localhost:3000) หรือยอมรับพอร์ตใดก็ได้ (http://localhost:*) เช่นเดียวกับโฮสต์ รูปแบบพอร์ตใดก็ได้ตรงกับ Origin ที่มีพอร์ตเท่านั้น Origin พอร์ตมาตรฐาน (https://app.example.com) ต้องระบุตรง
การจัดการ Host พร็อกซีย้อนกลับ

เก็บ Host เมื่อเป็นไปได้ ซึ่งทำให้ความเชื่อถือ Host ที่ส่งต่อถูกปิด:

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

ทำความสะอาด X-Forwarded-For และ X-Forwarded-Proto โดยอิสระจากความเชื่อถือ X-Forwarded-Host Uvicorn อาจเชื่อถือส่วนหัวเหล่านั้นตามเพียร์พร็อกซีแม้เมื่อ CLICKHOUSE_MCP_TRUSTED_PROXIES ไม่ได้ตั้ง

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com

nginx มาตรฐานเปลี่ยน Host เป็นชื่อต้นทางสำหรับคำขอที่พร็อกซี ไม่สร้างหรือเขียนทับ X-Forwarded-Host หากไม่สามารถเก็บ Host ได้ ให้เขียนทับส่วนหัวที่ส่งต่อที่ขอบที่เชื่อถือ:

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

การกำหนดค่าที่สองปลอดภัยเฉพาะเมื่อ 10.20.0.8 เป็นที่อยู่ต้นทางทันทีของพร็อกซี พอร์ตเซิร์ฟเวอร์ถูกแยกจากไคลเอ็นต์อื่น และ nginx เขียนทับส่วนหัวการส่งต่อที่เข้ามาตามที่แสดง สำหรับห่วงโซ่พร็อกซี แต่ละฮอปที่เชื่อถือต้องทิ้งค่าที่เข้ามาที่ไม่ได้รับการตรวจสอบก่อนสร้างส่วนหัวการส่งต่อใหม่

บนการผูก IPv6 หรือ dual-stack พร็อกซี IPv4 อาจปรากฏเป็นที่อยู่ที่แมป IPv4 เช่น ::ffff:10.20.0.8; สิ่งเหล่านี้ถูกจับคู่กับรายการ IPv4 โดยอัตโนมัติ append_x_forwarded_host ของ Envoy ผนวกเข้ากับ X-Forwarded-Host ที่มีอยู่แทนที่จะเขียนทับ ทำให้เกิดรายการที่คั่นด้วยเครื่องหมายจุลภาคที่ถูกปฏิเสธ ดังนั้นกำหนดค่าฮอปที่เชื่อถือให้เขียนทับส่วนหัวแทน บน Kubernetes ที่มี source NAT (เช่น externalTrafficPolicy: Cluster) เพียร์ที่สังเกตอาจเป็น IP โหนดแทนพ็อดพร็อกซี ดังนั้นเชื่อถือ CIDR พ็อดหรือโหนดตามความเหมาะสม; ingress-nginx เขียนทับทั้ง Host และ X-Forwarded-Host เอง

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

  • 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, reverse proxy หรือเข้าถึงผ่าน 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)

สำหรับ CA ของเซิร์ฟเวอร์ส่วนตัวโดยไม่มีการรับรองความถูกต้องด้วยใบรับรองไคลเอ็นต์:

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

สำหรับการรับรองความถูกต้องด้วยใบรับรองไคลเอ็นต์ X.509 ของ 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.

สำหรับใบรับรองไคลเอ็นต์ที่จำเป็นโดยเซิร์ฟเวอร์ TLS ที่เข้มงวดในขณะที่ ClickHouse ใช้การรับรองความถูกต้องแบบ 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

ใช้ CLICKHOUSE_TLS_MODE=proxy แทนเมื่อพร็อกซีที่ยุติ TLS ต้องการใบรับรองไคลเอ็นต์และ ClickHouse ยังคงใช้การรับรองความถูกต้องแบบ Basic

สำหรับ 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)
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:4200,localhost:4200,mcp.example.com:4200  # Include every Host value clients and proxies send

สำหรับการพัฒนาท้องถิ่นด้วยการขนส่ง HTTP (ปิดการรับรองความถูกต้อง):

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

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

  • จุดสิ้นสุด MCP: http://localhost:8000/mcp
  • การตรวจสอบสุขภาพ: http://localhost:8000/health

คุณสามารถตั้งค่าตัวแปรเหล่านี้ในสภาพแวดล้อมของคุณ ในไฟล์ .env หรือในการกำหนดค่า 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"
      }
    }
  }
}

หมายเหตุ: การตั้งค่าโฮสต์และพอร์ตสำหรับการผูกจะใช้เฉพาะเมื่อตั้งค่าการขนส่งเป็น "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