ClickHouse

ทางการ

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

GitHub
872
ลองใช้ MCP นี้ผู้สนับสนุน

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

  • รันคิวรี SQL — ขอให้ผู้ช่วยของคุณดำเนินการ SQL บนคลัสเตอร์ ClickHouse ผ่าน run_query รวมถึง DESCRIBE และ EXPLAIN ESTIMATE สำหรับการตรวจสอบเบื้องต้น
  • สำรวจโครงสร้างฐานข้อมูล — ใช้ list_databases และ list_tables เพื่อค้นหาฐานข้อมูล กรองตารางด้วยรูปแบบ LIKE และแบ่งหน้าผลลัพธ์ด้วย page_token
  • สอบถามข้อมูลด้วย chDB — ใช้ประโยชน์จาก run_chdb_select_query เพื่อรัน SQL กับเอ็นจิน chDB ในตัว สอบถามไฟล์ URL หรือฐานข้อมูลโดยไม่ต้องใช้ ETL
  • ตรวจสอบสุขภาพเซิร์ฟเวอร์ — ตรวจสอบจุดสิ้นสุด /health สำหรับการตรวจสอบ liveness/readiness โดยส่งคืน 200 OK เมื่อเชื่อมต่อหรือ 503 เมื่อเกิดข้อผิดพลาด
  • เปิดใช้งานการดำเนินการเขียน — กำหนดค่าตัวเลือก CLICKHOUSE_ALLOW_WRITE_ACCESS และ CLICKHOUSE_ALLOW_DROP เพื่ออนุญาต DDL/INSERT หรือการดำเนินการที่ทำลายล้างพร้อมการป้องกันความปลอดภัย

เอกสาร

เซิร์ฟเวอร์ ClickHouse MCP

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 ที่จะดำเนินการ
    • คิวรีทำงานในโหมดอ่านอย่างเดียวโดยค่าเริ่มต้น (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: จำนวนรวมของตารางที่ตรงกับตัวกรองที่ให้ไว้

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

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 (เนื้อหา: 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 ตัวแรกที่พบ และไม่โหลดอะไรเลยหากไม่มี ไม่เคยอ่านไดเรกทอรีทำงาน ไม่ว่าการเริ่มเซิร์ฟเวอร์จะเป็นอย่างไร การเช็คเอาต์ซอร์สโดยปกติจะพบ .env ที่รากของที่เก็บ ไฟล์นั้นอาจให้ FASTMCP_SERVER_AUTH และ ฟิลด์ผู้ให้บริการด้วย ค่าของไฟล์นั้นมีลำดับความสำคัญเหนือไฟล์การรับรองความถูกต้องที่ชัดเจนหรือแบบเข้ากันได้ สำหรับความเข้ากันได้กับ FastMCP 2 mcp-clickhouse อ่านฟิลด์ผู้ให้บริการที่ขาดหายไปจาก .env ในไดเรกทอรีทำงาน แต่การสำรองความเข้ากันได้นั้นไม่สามารถเลือก FASTMCP_SERVER_AUTH ได้ FASTMCP_ENV_FILE ที่ตั้งค่าในกระบวนการแทนที่การสำรองความเข้ากันได้นั้น และอาจให้ทั้งตัวเลือกและฟิลด์ผู้ให้บริการ ตั้งค่าก่อนเริ่มต้น ตัวโหลดความเข้ากันได้ของ mcp-clickhouse อ่านเฉพาะ FASTMCP_SERVER_AUTH และ FASTMCP_SERVER_AUTH_* จากไฟล์นั้น ดังนั้นจึงไม่สามารถแทรกการตั้งค่า CLICKHOUSE_* ได้ FastMCP 4 อาจใช้ไฟล์เดียวกันสำหรับการตั้งค่าที่กว้างขึ้นของตัวเอง ผู้ให้บริการที่กำหนดเอง ไม่ได้รับอาร์กิวเมนต์ตัวสร้างที่ได้จากสภาพแวดล้อมและต้องรองรับการสร้างโดยไม่มีอาร์กิวเมนต์

ปฏิบัติต่อไฟล์ .env ทั้งที่พบและในไดเรกทอรีทำงานเป็น การกำหนดค่าการรับรองความถูกต้องที่เชื่อถือได้ ใครก็ตามที่สามารถสร้างหรือเขียน .env ในไดเรกทอรีใด ๆ จากไดเรกทอรีแพ็กเกจ ขึ้นไปถึงรากของระบบไฟล์สามารถควบคุมไฟล์ที่พบ เลือก ผู้ให้บริการ และตั้งค่าฟิลด์ได้ ใครก็ตามที่สามารถเขียนไฟล์ในไดเรกทอรีทำงานควบคุมทุกฟิลด์ผู้ให้บริการ ที่ขาดหายไปจากการกำหนดค่ากระบวนการและที่พบ รวมถึงคีย์การลงนาม ผู้ออกและปลายทาง และความลับของไคลเอนต์ 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_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 จะถูกเพิกเฉย ดังนั้นจึงไม่ก่อให้เกิดการตรวจสอบหรือซ่อนคำสั่งจากการตรวจสอบ

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

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

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 เพื่อดำเนินการต่อในไปป์ไลน์

การกำหนดค่าไคลเอ็นต์แบบไดนามิกผ่านสถานะบริบท

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

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

ค่าสถานะต้องเป็นพจนานุกรม ค่า settings และ generic_args ที่ซ้อนกันต้องเป็น การแมปและถูกรวมกับการกำหนดค่าพื้นฐาน ค่าที่ไม่ถูกต้องจะทำให้การเรียกเครื่องมือล้มเหลวก่อน ที่ไคลเอ็นต์ 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 เก็บ ค่าในสถานะเฉพาะคำขอ serializable=True เริ่มต้นเก็บสถานะเซสชันและ ถูกปฏิเสธโดยเซิร์ฟเวอร์ เซิร์ฟเวอร์จับภาพค่าก่อนส่งงานฐานข้อมูลแบบบล็อก อย่าเก็บข้อมูลผู้เช่าในสถานะบริบทขอบเขตเซสชัน การแทนที่ขอบเขตเซสชันที่ถูกปฏิเสธ ยังคงแนบกับเซสชัน MCP เดิมและทำให้การเรียกเครื่องมือในเซสชันนั้นล้มเหลวในภายหลัง จนกว่าไคลเอ็นต์จะเชื่อมต่อใหม่ บทบาท ClickHouse ต่อคำขอคือการกำหนดค่าการเชื่อมต่อ ไม่ใช่ขอบเขตการอนุญาตผู้เช่า บังคับการแยกผู้เช่าด้วยผู้ใช้ บทบาท และสิทธิ์ ClickHouse

การพัฒนา

  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 เพื่อติดตั้ง dependencies หากต้องการติดตั้ง uv ทำตามคำแนะนำ ที่นี่ จากนั้นทำ source .venv/bin/activate

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

  3. หากต้องการทดสอบกับ HTTP transport และ 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

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

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

กลุ่มตัวแปรควบคุม
การเชื่อมต่อฐานข้อมูล ClickHouseCLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, ตัวแปรใบรับรองวิธีที่ เซิร์ฟเวอร์ MCP นี้ เชื่อมต่อกับคลัสเตอร์ ClickHouse ของคุณผ่าน อินเทอร์เฟซ HTTP
เซิร์ฟเวอร์ MCP / transportCLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*, FASTMCP_ENV_FILEMCP transport การรับรองความถูกต้อง และขีดจำกัดการดำเนินการเครื่องมือคิวรี
มิดเดิลแวร์ / 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 ใบรับรองไคลเอ็นต์ พอร์ต หรือการรับรองความถูกต้องสำหรับ MCP HTTP/SSE endpoint ขาเข้า

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

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

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

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

[!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 ที่สับสนแทนที่จะเป็นข้อความ "scheme ผิด" ที่ชัดเจน
  • CLICKHOUSE_VERIFY: เปิด/ปิดการตรวจสอบใบรับรอง SSL สำหรับการเชื่อมต่อ HTTPS ของ ClickHouse
    • ค่าเริ่มต้น: "true"
    • ตั้งค่าเป็น "false" เพื่อปิดการตรวจสอบใบรับรอง (ไม่แนะนำสำหรับการผลิต)
    • ใบรับรอง TLS: แพ็คเกจใช้ที่เก็บความน่าเชื่อถือของระบบปฏิบัติการของคุณผ่าน truststore.inject_into_ssl() เมื่อเริ่มต้น การจัดการ SSL เริ่มต้นของ Python จะถูกใช้หากการฉีดถูกปิดใช้งานด้วย MCP_CLICKHOUSE_TRUSTSTORE_DISABLE=1 หรือล้มเหลว
  • MCP_CLICKHOUSE_TRUSTSTORE_DISABLE: ปิดการรวมที่เก็บความน่าเชื่อถือของระบบปฏิบัติการทั่วทั้งกระบวนการสำหรับ TLS
    • ค่าเริ่มต้น: ไม่ได้ตั้งค่า (เปิดใช้การรวมที่เก็บความน่าเชื่อถือ)
    • ตั้งค่าเป็น "1" อย่างแม่นยำก่อนเริ่มต้นเพื่อข้าม truststore.inject_into_ssl() และใช้การจัดการใบรับรอง SSL เริ่มต้นของ Python ค่าอื่นๆ ไม่ได้ปิดการรวม
    • การดำเนินการนี้ไม่ได้ปิดการตรวจสอบใบรับรอง CLICKHOUSE_VERIFY ยังคงควบคุมการตรวจสอบสำหรับการเชื่อมต่อ HTTPS ของ ClickHouse
  • CLICKHOUSE_CA_CERT: เส้นทางไปยังชุดใบรับรอง CA แบบ PEM สำหรับการเชื่อมต่อ HTTPS ของ ClickHouse
    • ค่าเริ่มต้น: ไม่มี (ใช้ที่เก็บความน่าเชื่อถือของระบบปฏิบัติการ เว้นแต่การฉีด truststore จะถูกปิดใช้งานหรือล้มเหลว)
    • ใช้ค่านี้โดยลำพังเมื่อเซิร์ฟเวอร์ ClickHouse หรือพร็อกซีส่วนตัวนำเสนอใบรับรองที่ลงนามโดย CA ส่วนตัว การดำเนินการนี้เปลี่ยนการตรวจสอบใบรับรองเซิร์ฟเวอร์และไม่ได้เปิดใช้การตรวจสอบสิทธิ์ใบรับรองไคลเอ็นต์
    • ต้องใช้ CLICKHOUSE_SECURE=true และ CLICKHOUSE_VERIFY=true
  • CLICKHOUSE_CLIENT_CERT: เส้นทางไปยังใบรับรองไคลเอ็นต์แบบ PEM สำหรับการเชื่อมต่อ HTTPS ของ ClickHouse
    • ค่าเริ่มต้น: ไม่มี
    • ไฟล์อาจมีคีย์ส่วนตัวด้วย มิฉะนั้นให้ตั้งค่า CLICKHOUSE_CLIENT_CERT_KEY
    • ผู้ใช้ ClickHouse ยังคงมาจาก CLICKHOUSE_USER
  • CLICKHOUSE_CLIENT_CERT_KEY: เส้นทางไปยังคีย์ส่วนตัวแบบ PEM สำหรับ CLICKHOUSE_CLIENT_CERT
    • ค่าเริ่มต้น: ไม่มี
    • ไม่บังคับเมื่อคีย์ส่วนตัวรวมอยู่ในไฟล์ใบรับรองไคลเอ็นต์
    • ไม่สามารถใช้ได้หากไม่มี CLICKHOUSE_CLIENT_CERT
  • CLICKHOUSE_TLS_MODE: วิธีที่ clickhouse-connect ใช้ CLICKHOUSE_CLIENT_CERT
    • ค่าเริ่มต้น: ไม่มี ซึ่งทำงานเป็น "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
    • ค่าเริ่มต้น: ไม่มี (ใช้ชื่อโฮสต์การเชื่อมต่อ)
    • มีประโยชน์เมื่อเชื่อมต่อผ่านพร็อกซีหรือตัวโหลดบาลานซ์ที่ชื่อโฮสต์ใบรับรองแตกต่างจากชื่อโฮสต์การเชื่อมต่อ เมื่อตั้งค่าแล้ว ชื่อโฮสต์นี้จะถูกใช้ทั้งสำหรับ SNI (Server Name Indication) ระหว่างการจับมือ TLS และสำหรับการตรวจสอบชื่อโฮสต์ใบรับรอง
  • CLICKHOUSE_PROXY_PATH: คำนำหน้าเส้นทาง URL สำหรับจุดสิ้นสุด HTTP ของ ClickHouse
    • ค่าเริ่มต้น: ไม่มี
    • ตั้งค่านี้เมื่ออินเทอร์เฟซ HTTP ของ ClickHouse ถูกเปิดเผยด้านหลังพร็อกซีย้อนกลับภายใต้คำนำหน้าเส้นทาง (ตัวอย่างเช่น /clickhouse)
  • CLICKHOUSE_CONNECT_TIMEOUT: หมดเวลาการเชื่อมต่อเป็นวินาทีสำหรับไคลเอ็นต์ ClickHouse
    • ค่าเริ่มต้น: "30"
    • เพิ่มค่านี้หากคุณพบการหมดเวลาการเชื่อมต่อ
  • CLICKHOUSE_SEND_RECEIVE_TIMEOUT: หมดเวลาการส่ง/รับเป็นวินาทีสำหรับไคลเอ็นต์ ClickHouse
    • ค่าเริ่มต้น: ค่าที่ต่ำกว่าของ 300 หรือ CLICKHOUSE_MCP_QUERY_TIMEOUT + 5 เพื่อให้เธรดผู้ปฏิบัติงานปลดบล็อกไม่นานหลังจากการหมดเวลาคิวรี
    • หากตั้งค่าอย่างชัดเจน ค่าจะถูกใช้ตามที่เป็น (เช่น "300" สำหรับคิวรีที่ทำงานยาวนาน)
  • CLICKHOUSE_DATABASE: ฐานข้อมูล ClickHouse เริ่มต้นที่จะใช้
    • ค่าเริ่มต้น: ไม่มี (ใช้ค่าเริ่มต้นของเซิร์ฟเวอร์)
    • ตั้งค่านี้เพื่อเชื่อมต่อกับฐานข้อมูลเฉพาะโดยอัตโนมัติ
  • 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 ไม่ใช่ขอบเขตความปลอดภัย จำกัดสิทธิ์ของผู้ใช้ ClickHouse สำหรับการบังคับใช้จริง (ดู การป้องกันการดำเนินการที่ทำลาย)
ไฟล์ใบรับรอง 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: กำหนดวิธีการขนส่ง (transport) สำหรับ MCP server
    • ค่าเริ่มต้น: "stdio"
    • ตัวเลือกที่ถูกต้อง: "stdio", "http", "sse" ซึ่งมีประโยชน์สำหรับการพัฒนาท้องถิ่นกับเครื่องมืออย่าง MCP Inspector
    • stdio เป็นเรื่องปกติสำหรับ Claude Desktop; http/sse เปิดเผย network listener (ผูก host/port ด้านล่าง)
    • "sse" เลือก transport แบบ HTTP+SSE แบบสแตนด์อโลนที่เลิกใช้งานแล้วและบันทึกคำเตือน ใช้ "http" สำหรับ Streamable HTTP ในการติดตั้งใหม่
  • CLICKHOUSE_MCP_BIND_HOST: Host ที่จะผูก MCP server เมื่อใช้ HTTP หรือ SSE transport
    • ค่าเริ่มต้น: "127.0.0.1"
    • ตั้งเป็น "0.0.0.0" เพื่อผูกกับอินเทอร์เฟซเครือข่ายทั้งหมด (มีประโยชน์สำหรับ Docker หรือการเข้าถึงระยะไกล)
    • ใช้เฉพาะเมื่อ transport เป็น "http" หรือ "sse" — ไม่เกี่ยวข้องกับ CLICKHOUSE_HOST
  • CLICKHOUSE_MCP_BIND_PORT: Port ที่จะผูก MCP server เมื่อใช้ HTTP หรือ SSE transport
    • ค่าเริ่มต้น: "8000"
    • ใช้เฉพาะเมื่อ transport เป็น "http" หรือ "sse" — ไม่เกี่ยวข้องกับ CLICKHOUSE_PORT
  • CLICKHOUSE_MCP_QUERY_TIMEOUT: หมดเวลาในหน่วยวินาทีสำหรับการเรียกใช้เครื่องมือ query
    • ค่าเริ่มต้น: "30"
    • เพิ่มค่านี้หากคุณเห็นข้อผิดพลาด Query timed out after ... สำหรับ query ที่หนัก
    • เมื่อ query หมดเวลา server จะพยายามยกเลิกด้วย KILL QUERY
    • เว้นแต่ CLICKHOUSE_SEND_RECEIVE_TIMEOUT จะถูกตั้งไว้อย่างชัดเจน หมดเวลาการอ่าน HTTP จะถูกจำกัดที่ค่านี้บวกห้าวินาที
  • CLICKHOUSE_MCP_MAX_WORKERS: จำนวนสูงสุดของเธรด worker query พร้อมกัน
    • ค่าเริ่มต้น: "10"
    • เพิ่มหากปริมาณงานของคุณต้องการการเรียกใช้เครื่องมือพร้อมกันจำนวนมาก
    • เครื่องมือ metadata ใช้พูลแยกกับ min(4, CLICKHOUSE_MCP_MAX_WORKERS) เธรด เพื่อให้การค้นพบ schema ไม่ทำให้ query ล่าช้า
  • CLICKHOUSE_MCP_AUTH_TOKEN: โทเค็น bearer แบบคงที่สำหรับ HTTP/SSE transports
    • ค่าเริ่มต้น: ไม่มี
    • หนึ่งใน CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH, หรือ CLICKHOUSE_MCP_AUTH_DISABLED=true จำเป็น สำหรับ HTTP/SSE transports
    • สร้างโดยใช้ uuidgen หรือ openssl rand -hex 32
    • ไคลเอนต์ต้องส่งโทเค็นนี้ในส่วนหัว Authorization: Bearer <token>
  • FASTMCP_SERVER_AUTH: มอบหมายการรับรองความถูกต้องให้กับ FastMCP auth provider
    • ค่าเริ่มต้น: ไม่มี
    • ค่าคือ full class path ของคลาสย่อย AuthProvider เช่น fastmcp.server.auth.providers.azure.AzureProvider หรือ fastmcp.server.auth.providers.google.GoogleProvider
    • เมื่อตั้งค่า mcp-clickhouse จะโหลด provider จากตัวแปรสภาพแวดล้อม FASTMCP_SERVER_AUTH_* ที่มีอยู่; ปล่อย CLICKHOUSE_MCP_AUTH_TOKEN ไม่ได้ตั้งค่าในโหมดนี้
    • ผู้ให้บริการที่กำหนดเองไม่ได้รับอาร์กิวเมนต์ constructor ที่มาจากสภาพแวดล้อมและต้องรองรับการสร้างแบบไม่มีอาร์กิวเมนต์
    • FastMCP 4 ไม่รองรับการตรวจสอบ Supabase HS256 อีกต่อไป การติดตั้ง Supabase ต้องใช้ RS256 หรือ ES256
  • FASTMCP_ENV_FILE: ไฟล์ทางเลือกที่มี FASTMCP_SERVER_AUTH และตัวแปรสภาพแวดล้อมเฉพาะผู้ให้บริการ
    • ค่าเริ่มต้น: ไม่มี เมื่อไม่ได้ตั้งค่า ตัวโหลดความเข้ากันได้จะอ่านฟิลด์ผู้ให้บริการที่ขาดหายไปจาก .env ในไดเรกทอรีทำงาน ไม่ได้อ่าน FASTMCP_SERVER_AUTH จาก fallback นั้น
    • ตั้งค่าในสภาพแวดล้อมของกระบวนการก่อนเริ่มต้น ค่าที่โหลดจาก .env เริ่มต้นไม่สามารถเปลี่ยนเส้นทางตัวโหลดความเข้ากันได้
    • หากตั้งค่าผ่านกระบวนการ ไฟล์นี้อาจให้ทั้ง FASTMCP_SERVER_AUTH และฟิลด์ผู้ให้บริการ และแทนที่ fallback ของไดเรกทอรีทำงาน
    • ค่าสภาพแวดล้อมของกระบวนการมีความสำคัญเหนือกว่าแบบไม่คำนึงถึงตัวพิมพ์เล็กใหญ่
    • ตัวโหลดความเข้ากันได้ของ mcp-clickhouse อ่านไฟล์นี้เฉพาะเมื่อสร้างการรับรองความถูกต้อง HTTP/SSE และอ่านเฉพาะรายการ FASTMCP_SERVER_AUTH และ FASTMCP_SERVER_AUTH_* เท่านั้น FastMCP 4 อาจอ่านไฟล์เดียวกันสำหรับการตั้งค่าที่กว้างขึ้น
    • การโหลด .env เริ่มต้นแยกต่างหาก เริ่มต้นที่ไดเรกทอรีแพ็คเกจ mcp_clickhouse ที่ติดตั้ง แก้ไข symlinks เดินขึ้นไปยังรากของระบบไฟล์ และโหลด .env ตัวแรกที่พบหรือไม่มีเลย ไม่เคยอ่านไดเรกทอรีทำงาน ไม่ว่าจะเปิดตัวด้วยวิธีใด ไฟล์นั้นอาจให้ FASTMCP_SERVER_AUTH และฟิลด์ผู้ให้บริการพร้อมกับการตั้งค่า server อื่นๆ การ checkout จากซอร์สมักจะพบ .env ที่รากของ repository
  • CLICKHOUSE_MCP_AUTH_DISABLED: ปิดการรับรองความถูกต้องสำหรับ HTTP/SSE transports
    • ค่าเริ่มต้น: "false" (เปิดการรับรองความถูกต้อง)
    • ตั้งเป็น "true" เพื่อปิดการรับรองความถูกต้องสำหรับการพัฒนาท้องถิ่น/การทดสอบเท่านั้น
    • คำเตือน: ใช้สำหรับการพัฒนาท้องถิ่นเท่านั้น อย่าปิดเมื่อเปิดเผยต่อเครือข่าย
  • CLICKHOUSE_MCP_ALLOWED_HOSTS: ค่าของส่วนหัว Host ที่คั่นด้วยเครื่องหมายจุลภาคที่ HTTP/SSE server ตอบสนอง
    • ค่าเริ่มต้นสำหรับการผูก loopback: รูปแบบ bare และ any-port ของ 127.0.0.1, localhost, และ [::1]
    • หากตั้งค่า ค่าต้องมีรายการ Host อย่างน้อยหนึ่งรายการ
    • ที่อยู่ผูกที่ไม่ใช่ loopback ที่เป็นรูปธรรมจะเริ่มต้นที่ที่อยู่นั้นและ port ที่กำหนดค่า การผูกแบบ wildcard เช่น 0.0.0.0 หรือ :: ต้องมีค่าที่ไม่ว่างอย่างชัดเจนเนื่องจากไม่สามารถอนุมาน Host สาธารณะได้
    • การตรวจสอบ Host เป็นการป้องกันเชิงลึกต่อ DNS rebinding การตรวจสอบ Origin ด้านล่างจำเป็นแยกต่างหากโดย MCP
    • รายการเป็นแบบตรง (localhost:8000) หรือยอมรับ port ใดก็ได้ (localhost:*) ตัวอย่าง: CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000
    • รูปแบบ host:* ตรงกับค่าที่มี port เท่านั้น Host ที่ไม่มี port (การติดตั้ง standard-port ที่ไคลเอนต์ละ :80/:443) ต้องระบุเป็นรายการตรงแบบ bare (example.com) ด้วย
    • คำขอที่มีส่วนหัว Host ที่ไม่ตรงหรือขาดหายไปจะได้รับ 421 Misdirected Request คำขอ GET และ HEAD ไปยัง /health ได้รับการยกเว้นจากการตรวจสอบ Host และ Origin เพื่อให้การตรวจสอบ orchestrator ทำงานต่อไป
    • ด้านหลัง reverse proxy ควรเก็บส่วนหัว Host เดิมไว้ คุณสามารถระบุค่าของ Host ต้นทางที่ proxy ส่งแทนได้ ตั้งค่ารายการอย่างชัดเจนเมื่อ launcher เช่น 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 ของ proxy หรือเครือข่าย 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 แบบ scoped *, 0.0.0.0/0, และ ::/0 ถูกปฏิเสธเช่นกัน
    • ความเชื่อถือขึ้นอยู่กับ peer ของ raw socket ทันที คำขอจาก peer อื่น หรือคำขอที่ไม่มีที่อยู่ไคลเอนต์ จะละเว้น X-Forwarded-Host และตรวจสอบ Host
    • peer ที่เชื่อถืออาจส่งส่วนหัว X-Forwarded-Host หนึ่งรายการที่มีค่าที่ไม่ว่างหนึ่งค่า ฟิลด์ที่ซ้ำกัน ค่าว่าง และรายการที่คั่นด้วยเครื่องหมายจุลภาคจะได้รับ 421 Misdirected Request หากไม่มีส่วนหัว Host จะถูกตรวจสอบ
    • ใช้ที่อยู่หรือเครือข่ายที่แคบที่สุดเท่าที่เป็นไปได้ MCP server ต้องเข้าถึงได้ผ่าน proxy ในช่วงที่กำหนดเท่านั้น proxy ที่เชื่อถือทุกตัวต้องลบและเขียนทับค่าที่ไคลเอนต์ส่ง X-Forwarded-Host และ X-Forwarded-Proto และสร้าง X-Forwarded-For จาก peer การเชื่อมต่อที่ตรวจสอบแล้ว
    • server ในตัวและ fastmcp run ปิดการจัดการ proxy-header ภายนอกของ Uvicorn ตรวจสอบ Host จาก raw peer จากนั้นใช้ X-Forwarded-For และ X-Forwarded-Proto การเปิดใช้งาน uvicorn_config["proxy_headers"] อย่างชัดเจนจะทำให้การเริ่มต้นล้มเหลวในโหมดนี้
    • การฝัง ASGI โดยตรงต้องปิดการจัดการ proxy-header ใน ASGI server ภายนอกและเรียก mcp.http_app(raw_client_address_preserved=True) หากไม่มีการยืนยันอย่างชัดเจนนั้น การสร้างแอปจะล้มเหลวเมื่อมีการกำหนดค่า proxy ที่เชื่อถือ
  • CLICKHOUSE_MCP_ALLOWED_ORIGINS: ค่าของส่วนหัว Origin ที่คั่นด้วยเครื่องหมายจุลภาคที่ยอมรับบน HTTP/SSE
    • ค่าเริ่มต้น: ไม่มี ซึ่งปฏิเสธทุกคำขอที่มีส่วนหัว Origin
    • MCP ต้องการการตรวจสอบ Origin สำหรับการเชื่อมต่อ HTTP/SSE transport คำขอที่ไม่มี Origin จะถูกยอมรับเนื่องจากไคลเอนต์ MCP ที่ไม่ใช่เบราว์เซอร์มักละเว้น Origin ที่ไม่ตรงจะได้รับ 403 Forbidden ปลายทาง /health ได้รับการยกเว้นตามที่อธิบายไว้ข้างต้น
    • รายการเป็นแบบตรง (http://localhost:3000) หรือยอมรับ port ใดก็ได้ (http://localhost:*) เช่นเดียวกับ host รูปแบบ any-port ตรงกับ origin ที่มี port เท่านั้น origin แบบ standard-port (https://app.example.com) ต้องระบุอย่างตรง
การจัดการ Host ของ Reverse Proxy

เก็บ 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 อาจเชื่อถือส่วนหัวเหล่านั้นตาม peer proxy แม้ว่า CLICKHOUSE_MCP_TRUSTED_PROXIES จะไม่ได้ตั้งค่า

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com

nginx มาตรฐานเปลี่ยน Host เป็นชื่อต้นทางสำหรับคำขอที่ส่งผ่าน proxy ไม่ได้สร้างหรือเขียนทับ 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 เป็นที่อยู่ต้นทางทันทีของ proxy port ของ server ถูกแยกจากไคลเอนต์อื่น และ nginx เขียนทับส่วนหัวการส่งต่อที่เข้ามาตามที่แสดง สำหรับ chain ของ proxy แต่ละ hop ที่เชื่อถือต้องทิ้งค่าที่เข้ามาที่ไม่ได้รับการตรวจสอบก่อนสร้างส่วนหัวการส่งต่อใหม่

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

ตัวแปร Middleware

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

ตัวแปร chDB

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

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

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

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

สำหรับการพัฒนาท้องถิ่นกับ 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 ของ server ส่วนตัวโดยไม่มีการรับรองความถูกต้องใบรับรองไคลเอนต์:

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.

สำหรับใบรับรองไคลเอนต์ที่จำเป็นโดย server 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 transport:

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 transport (ปิดการรับรองความถูกต้อง):

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 transport เซิร์ฟเวอร์จะทำงานบนพอร์ตที่กำหนดค่าไว้ (ค่าเริ่มต้น 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"
      }
    }
  }
}

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