ClickHouse

आधिकारिक

अपने ClickHouse डेटाबेस सर्वर से क्वेरी करें।

GitHub
877

ClickHouse MCP के साथ आप क्या कर सकते हैं?

  • SQL क्वेरी चलाएँ — अपने ClickHouse क्लस्टर पर run_query के माध्यम से कोई भी SQL क्वेरी निष्पादित करने के लिए कहें, वैकल्पिक नामित पैरामीटर के साथ।
  • डेटाबेस सूचीबद्ध करें — list_databases का उपयोग करके अपने ClickHouse क्लस्टर पर उपलब्ध सभी डेटाबेस देखने के लिए कहें।
  • फ़िल्टर के साथ तालिकाएँ ब्राउज़ करें — list_tables के माध्यम से LIKE/NOT LIKE पैटर्न और पेजिनेशन के साथ किसी डेटाबेस में तालिकाओं की सूची देखने के लिए कहें।
  • क्वेरी स्कीमा जाँचें — DESCRIBE का उपयोग करके क्वेरी चलाने से पहले उसके आउटपुट कॉलम और प्रकारों की जाँच करने के लिए कहें।
  • क्वेरी लागत का अनुमान लगाएँ — EXPLAIN ESTIMATE का उपयोग करके SELECT के लिए अनुमानित रीड्स (भाग, पंक्तियाँ, मार्क्स) का पूर्वावलोकन करने के लिए कहें।

दस्तावेज़

ClickHouse MCP सर्वर

PyPI - Version

ClickHouse के लिए एक MCP सर्वर।

mcp-clickhouse MCP server

सर्वर MCP 2026-07-28 लागू करता है और 2024-11-05 से 2025-11-25 तक के लीगेसी initialize हैंडशेक का समर्थन करता है। आधुनिक क्लाइंट sessionless अनुरोध और server/discover का उपयोग करते हैं। मौजूदा क्लाइंट लीगेसी प्रोटोकॉल पर बातचीत जारी रख सकते हैं।

[!NOTE] MCP-Protocol-Version के बिना HTTP अनुरोध लीगेसी हैंडलिंग के माध्यम से रूट किए जाते हैं ताकि 2025-06-18 से पहले के क्लाइंट कनेक्ट हो सकें। MCP 2026-07-28 सर्वरों को यह व्यवहार करने की अनुमति देता है जो उन क्लाइंटों का समर्थन करते हैं। आधुनिक क्लाइंट को हर POST अनुरोध पर हेडर भेजना चाहिए।

विशेषताएँ

ClickHouse उपकरण

ClickHouse उपकरण प्रतिक्रियाएँ JSON-एन्कोडेड स्ट्रिंग्स हैं। [-9007199254740991, 9007199254740991] के बाहर के पूर्णांक जावास्क्रिप्ट क्लाइंटों में सटीक मान संरक्षित करने के लिए दशमलव स्ट्रिंग्स के रूप में लौटाए जाते हैं। यह क्वेरी पंक्तियों और पूर्णांक तालिका मेटाडेटा पर लागू होता है। सुरक्षित-सीमा के पूर्णांक और बूलियन अपने JSON प्रकार बनाए रखते हैं।

  • run_query

    • अपने ClickHouse क्लस्टर पर SQL क्वेरी निष्पादित करें।
    • इनपुट: query (स्ट्रिंग): निष्पादित करने के लिए SQL क्वेरी।
    • वैकल्पिक इनपुट: params (ऑब्जेक्ट): ClickHouse {name:Type} प्लेसहोल्डर्स के लिए नामित मान। क्वेरी पैरामीटर देखें।
    • क्वेरी डिफ़ॉल्ट रूप से केवल-पढ़ने के मोड में चलती हैं (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: प्रदान किए गए फ़िल्टर से मेल खाने वाली तालिकाओं की कुल संख्या।

क्वेरी पैरामीटर

वैकल्पिक params ऑब्जेक्ट के माध्यम से SQL से अलग मान पास करें:

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

ClickHouse के {name:Type} प्लेसहोल्डर्स का उपयोग बिना उद्धरण के करें। खुला ब्रेस, नाम और कोलन को सटे रखें, जैसे {id:UInt32} में। कोलन के बाद और प्रकार के भीतर रिक्त स्थान समर्थित हैं, जैसे {id: UInt32} और {amount:Decimal(18, 4)} में। समर्थित ड्राइवर संस्करणों में संगतता के लिए, नाम अक्षर या अंडरस्कोर से शुरू करें और केवल अक्षर, अंक और अंडरस्कोर का उपयोग करें। पायथन-शैली %s या %(name)s फ़ॉर्मेटिंग और ड्राइवर के $name$ कच्चे बाइनरी पैरामीटर समर्थित नहीं हैं। केवल query वाले कॉल अभी भी काम करते हैं। params छोड़ना, null पास करना, या खाली ऑब्जेक्ट पास करना क्वेरी को अनबाउंड छोड़ देता है।

पैरामीटर मान JSON स्ट्रिंग्स, संख्याएँ, बूलियन, null या सरणियाँ हो सकते हैं, बशर्ते वे घोषित ClickHouse प्रकार से मेल खाते हों:

  • null प्रकार के साथ Nullable(...) का उपयोग करें।
  • जावास्क्रिप्ट की सुरक्षित सीमा से बाहर के सटीक पूर्णांक दशमलव स्ट्रिंग्स के रूप में पास करें, उदाहरण के लिए "18446744073709551615" के साथ {id:UInt64}। दिनांक, टाइमस्टैम्प और सटीक दशमलव भी संबंधित ClickHouse प्रकार के साथ स्ट्रिंग्स के रूप में पास किए जा सकते हैं।
  • वेक्टरों को एक सरणी के रूप में बाँधें, उदाहरण के लिए {vector:Array(Float32)} के साथ "params": {"vector": [0.25, 0.5, 0.75]}।
  • सरणियों के अंदर Nulls स्थापित ड्राइवर पर निर्भर करते हैं। वे clickhouse-connect 1.8.0 के साथ काम करते हैं लेकिन समर्थित न्यूनतम 1.0.0 के साथ विफल होते हैं।
  • JSON सूचियाँ और ऑब्जेक्ट ClickHouse Tuple और Map प्रकारों से बाइंड नहीं हो सकते।

लापता मान और असंगत प्रकार क्वेरी त्रुटियाँ लौटाते हैं। गैर-खाली params के साथ, कई अपूर्ण {name: प्लेसहोल्डर शुरुआत वाली क्वेरी अस्वीकार कर दी जाती है, जिसमें टिप्पणियों या स्ट्रिंग शाब्दिकों में प्लेसहोल्डर-जैसा पाठ शामिल है। पैरामीटरयुक्त क्वेरी अन्य क्वेरी के समान लेखन सुरक्षा, टाइमआउट, रद्दीकरण और JSON परिणाम एन्कोडिंग का उपयोग करती हैं।

पैरामीटर मान MCP सर्वर के सामान्य SQL लॉग संदेशों से बाहर रहते हैं, लेकिन 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 के तहत काम करते हैं। EXPLAIN ESTIMATE और DESCRIBE के लिए ClickHouse दस्तावेज़ देखें।

chDB उपकरण

  • run_chdb_select_query
    • chDB के एम्बेडेड ClickHouse इंजन का उपयोग करके SQL क्वेरी निष्पादित करें।
    • इनपुट: query (स्ट्रिंग): निष्पादित करने के लिए SQL क्वेरी।
    • [-9007199254740991, 9007199254740991] के बाहर के पूर्णांक दशमलव स्ट्रिंग्स के रूप में लौटाए जाते हैं।
    • ETL प्रक्रियाओं के बिना विभिन्न स्रोतों (फ़ाइलें, URL, डेटाबेस) से सीधे डेटा क्वेरी करें।
    • वैकल्पिक 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, लोड बैलेंसर) अतिरिक्त कॉन्फ़िगरेशन के बिना रनटाइम-असाइन किए गए पॉड या लक्ष्य IP का उपयोग कर सकें। /health आरक्षित है और MCP ट्रांसपोर्ट पथ के रूप में उपयोग नहीं किया जा सकता है। प्रतिक्रिया बॉडी जानबूझकर न्यूनतम है ताकि बैकएंड संस्करण स्ट्रिंग्स या त्रुटि विवरण लीक न हों; सर्वर लॉग के माध्यम से डीबग विफलताएँ।

उदाहरण:

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

सुरक्षा

HTTP/SSE ट्रांसपोर्ट के लिए प्रमाणीकरण

HTTP या SSE ट्रांसपोर्ट का उपयोग करते समय, प्रमाणीकरण डिफ़ॉल्ट रूप से आवश्यक है। stdio ट्रांसपोर्ट (डिफ़ॉल्ट) को प्रमाणीकरण की आवश्यकता नहीं है क्योंकि यह केवल मानक इनपुट/आउटपुट के माध्यम से संचार करता है।

तीन प्रमाणीकरण मोड समर्थित हैं। एक चुनें:

मोडकब उपयोग करेंEnv var
स्थिर बियरर टोकनसरल तैनाती, आंतरिक सेवाएँCLICKHOUSE_MCP_AUTH_TOKEN
OAuth / OIDC (FastMCP के माध्यम से)Azure Entra, Google, GitHub, WorkOS, आदि।FASTMCP_SERVER_AUTH=<provider-class-path> (+ प्रदाता-विशिष्ट FASTMCP_SERVER_AUTH_* vars)
अक्षमकेवल स्थानीय विकास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 क्लाइंट को अनुरोधों में टोकन शामिल करने के लिए कॉन्फ़िगर करें:

    HTTP/SSE ट्रांसपोर्ट के साथ Claude Desktop के लिए:

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

    नोट: /health एंडपॉइंट जानबूझकर अनप्रमाणित है (ऊपर स्वास्थ्य जाँच एंडपॉइंट देखें)। यह सत्यापित करने के लिए कि बियरर-टोकन प्रमाणीकरण वास्तव में अनप्रमाणित अनुरोधों को अस्वीकार कर रहा है, MCP एंडपॉइंट को ही हिट करें जैसे MCP Inspector के साथ, या /mcp पर Authorization हेडर के साथ और बिना JSON-RPC अनुरोध POST करके और पुष्टि करें कि अनप्रमाणित कॉल 401 लौटाता है।

FastMCP के माध्यम से OAuth / OIDC

पहचान प्रदाताओं (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 4.0.0 अंतर्निहित प्रदाताओं के लिए इन FastMCP 2.14.7 पर्यावरण उपसर्गों को बनाए रखता है:

प्रदाता क्लास पथप्रदाता चर उपसर्ग
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 पैकेज निर्देशिका से शुरू होती है, पहले सिमलिंक हल करती है, और फाइलसिस्टम रूट तक ऊपर की ओर बढ़ती है। यह पहली .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 प्रॉक्सी क्लाइंट स्टोर बदल दिया। वे तैनातियाँ जो FastMCP 2 के डिफ़ॉल्ट OAuth प्रॉक्सी स्टोरेज पर निर्भर थीं, उन्हें क्लाइंट को फिर से पंजीकृत और अधिकृत कराना होगा। संगत कस्टम स्टोरेज, स्थिर बियरर टोकन, और 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 का सही संस्करण उपयोग किया जाए। मैक पर, आप 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 टिप्पणियों और {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;

इन अनुदानों के बाहर हर स्टेटमेंट तब MCP फ़्लैग की परवाह किए बिना सर्वर-साइड ACCESS_DENIED के साथ विफल हो जाता है। सर्वर सेटिंग्स 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 का उपयोग करके)

यदि आप uv के बजाय सिस्टम Python इंस्टॉलेशन का उपयोग करना पसंद करते हैं, तो आप 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. Python का सीधे उपयोग करने के लिए अपने Claude Desktop कॉन्फ़िगरेशन को अपडेट करें:

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

नोट: यदि वे आपके सिस्टम PATH में नहीं हैं तो Python निष्पादन योग्य या mcp-clickhouse स्क्रिप्ट का पूर्ण पथ उपयोग करना सुनिश्चित करें। आप पथ निम्न का उपयोग करके पा सकते हैं:

  • Python निष्पादन योग्य के लिए which python3
  • इंस्टॉल की गई स्क्रिप्ट के लिए which mcp-clickhouse

कस्टम मिडलवेयर

आप स्रोत कोड को संशोधित किए बिना MCP सर्वर में कस्टम मिडलवेयर जोड़ सकते हैं। FastMCP एक मिडलवेयर सिस्टम प्रदान करता है जो आपको MCP प्रोटोकॉल संदेशों (टूल कॉल, संसाधन पठन, प्रॉम्प्ट, आदि) को इंटरसेप्ट और प्रोसेस करने की अनुमति देता है।

उपयोग कैसे करें

  1. Middleware का विस्तार करने वाले मिडलवेयर वर्गों और एक setup_middleware(mcp) फ़ंक्शन के साथ एक Python मॉड्यूल बनाएं:
# 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 फ़ंक्शन प्राप्त होता है।

संदर्भ स्थिति के माध्यम से गतिशील क्लाइंट कॉन्फ़िगरेशन

मिडलवेयर CLIENT_CONFIG_OVERRIDES_KEY संदर्भ स्थिति कुंजी का उपयोग करके प्रति-अनुरोध आधार पर ClickHouse क्लाइंट कॉन्फ़िगरेशन को ओवरराइड कर सकता है। सर्वर इन ओवरराइड्स को पर्यावरण चरों से आधार कॉन्फ़िगरेशन के साथ मर्ज करता है।

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 अनसेट होने पर tls_mode: proxy के रूप में व्यवहार करता है और इसलिए पर्यावरण पासवर्ड के साथ बेसिक प्रमाणीकरण का उपयोग करता है। एक secure ओवरराइड मेल खाते https या http इंटरफ़ेस का चयन करता है और पोर्ट नहीं बदलता। एक स्पष्ट interface ओवरराइड http या https होना चाहिए और secure से सहमत होना चाहिए। ओवरराइड मर्ज करने के बाद, डिफ़ॉल्ट और mutual क्लाइंट प्रमाणपत्र मोड पासवर्ड छोड़ देते हैं। proxy और strict मोड पर्यावरण पासवर्ड के साथ बेसिक प्रमाणीकरण का उपयोग करते हैं जब तक कि ओवरराइड अपनी स्वयं की क्रेडेंशियल प्रदान न करे।

इन ओवरराइड्स को विश्वसनीय मिडलवेयर इनपुट मानें। मिडलवेयर को उन्हें सेट करने से पहले अनुरोध-व्युत्पन्न मानों को प्रमाणित और अधिकृत करना चाहिए। serializable=False का उपयोग करें ताकि FastMCP मान को अनुरोध-स्थानीय स्थिति में रखे। डिफ़ॉल्ट serializable=True सत्र स्थिति संग्रहीत करता है और सर्वर द्वारा अस्वीकार कर दिया जाता है। सर्वर ब्लॉकिंग डेटाबेस कार्य भेजने से पहले मान का स्नैपशॉट लेता है। सत्र-स्कोप्ड संदर्भ स्थिति में टेनेंट डेटा संग्रहीत न करें। एक अस्वीकृत सत्र-स्कोप्ड ओवरराइड एक विरासत MCP सत्र से जुड़ा रहता है और उस सत्र में बाद के टूल कॉल को विफल कर देता है जब तक क्लाइंट पुनः कनेक्ट न हो। एक प्रति-अनुरोध ClickHouse भूमिका कनेक्शन कॉन्फ़िगरेशन है, टेनेंट प्राधिकरण सीमा नहीं। ClickHouse उपयोगकर्ताओं, भूमिकाओं और अनुदानों के साथ टेनेंट अलगाव लागू करें।

विकास

  1. test-services निर्देशिका में ClickHouse क्लस्टर शुरू करने के लिए docker compose up -d चलाएँ।

  2. रिपॉजिटरी के रूट में एक .env फ़ाइल में निम्नलिखित चर जोड़ें।

नोट: इस संदर्भ में default उपयोगकर्ता का उपयोग केवल स्थानीय विकास उद्देश्यों के लिए है।

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

  1. निर्भरताएँ इंस्टॉल करने के लिए uv sync चलाएँ। uv इंस्टॉल करने के लिए यहाँ दिए गए निर्देशों का पालन करें। फिर source .venv/bin/activate करें।

  2. MCP Inspector के साथ आसान परीक्षण के लिए, MCP सर्वर शुरू करने के लिए uv run fastmcp dev inspector mcp_clickhouse/mcp_server.py:mcp चलाएँ।

  3. HTTP ट्रांसपोर्ट और स्वास्थ्य जाँच एंडपॉइंट के साथ परीक्षण करने के लिए:

    # 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

पर्यावरण चर

कॉन्फ़िगरेशन स्वतंत्र समूहों में विभाजित है। उन्हें मिलाना कठिन-से-डीबग कनेक्शन विफलताओं का एक सामान्य कारण है:

समूहचरनियंत्रण
ClickHouse डेटाबेस कनेक्शनCLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, प्रमाणपत्र चरयह MCP सर्वर आपके ClickHouse क्लस्टर से HTTP इंटरफ़ेस पर कैसे जुड़ता है
MCP सर्वर / ट्रांसपोर्टCLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*, FASTMCP_ENV_FILEMCP ट्रांसपोर्ट, प्रमाणीकरण, और क्वेरी-टूल निष्पादन सीमाएँ
मिडलवेयर / 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 डेटाबेस कनेक्शन पर लागू होते हैं। वे इनबाउंड MCP HTTP/SSE एंडपॉइंट के लिए TLS, क्लाइंट प्रमाणपत्र, पोर्ट, या प्रमाणीकरण कॉन्फ़िगर नहीं करते हैं।

उदाहरण: यदि MCP सर्वर Kubernetes में एक इनग्रेस के पीछे चलता है जो TLS समाप्त करता है, तो यह एक MCP ट्रांसपोर्ट चिंता है। CLICKHOUSE_SECURE को इस बात के साथ संरेखित रखें कि पॉड स्वयं ClickHouse तक कैसे पहुँचता है (HTTPS → true, सादा HTTP → false)। CLICKHOUSE_SECURE=false को केवल इसलिए सेट करना क्योंकि MCP सर्वर एक इनग्रेस के पीछे है, सर्वर को ClickHouse पर HTTP के माध्यम से कॉल करने के लिए प्रेरित करेगा—अक्सर केवल-HTTPS पोर्ट के विरुद्ध—और सर्वर लॉग में अस्पष्ट HTTP/TLS त्रुटियाँ उत्पन्न करेगा।

ClickHouse डेटाबेस कनेक्शन

ये चर clickhouse-connect HTTP क्लाइंट और ClickHouse-आधारित टूल जैसे run_query, list_databases, और list_tables के व्यवहार को कॉन्फ़िगर करते हैं। mcp-clickhouse को clickhouse-connect 1.x की आवश्यकता है, जो 1.0.0 से शुरू होता है।

आवश्यक चर
  • CLICKHOUSE_HOST: आपके ClickHouse सर्वर का होस्टनाम (डेटाबेस एंडपॉइंट, MCP सर्वर बाइंड पता नहीं)
  • CLICKHOUSE_USER: ClickHouse प्रमाणीकरण के लिए उपयोगकर्ता नाम
  • CLICKHOUSE_PASSWORD: ClickHouse प्रमाणीकरण के लिए पासवर्ड
    • आवश्यक है जब तक कि CLICKHOUSE_CLIENT_CERT डिफ़ॉल्ट या "mutual" TLS मोड का उपयोग न करे
    • डिफ़ॉल्ट या "mutual" मोड में, प्रमाणपत्र प्रमाणीकरण का उपयोग किया जाता है और पासवर्ड नहीं भेजा जाता है

[!CAUTION] अपने MCP डेटाबेस उपयोगकर्ता को उसी तरह व्यवहार करना महत्वपूर्ण है जैसे आप अपने डेटाबेस से जुड़ने वाले किसी भी बाहरी क्लाइंट के साथ करते हैं, केवल उसके संचालन के लिए आवश्यक न्यूनतम विशेषाधिकार प्रदान करते हैं। डिफ़ॉल्ट या प्रशासनिक उपयोगकर्ताओं का उपयोग हर समय सख्ती से टाला जाना चाहिए।

वैकल्पिक चर
  • CLICKHOUSE_PORT: आपके ClickHouse सर्वर का HTTP इंटरफ़ेस पोर्ट
    • डिफ़ॉल्ट: 8443 यदि CLICKHOUSE_SECURE=true, 8123 यदि CLICKHOUSE_SECURE=false
    • आमतौर पर सेट करने की आवश्यकता नहीं होती जब तक कि गैर-मानक पोर्ट का उपयोग न किया जा रहा हो
    • HTTP इंटरफ़ेस पोर्ट होना चाहिए, clickhouse-client द्वारा उपयोग किया जाने वाला नेटिव TCP प्रोटोकॉल पोर्ट नहीं
    • सामान्य मान:
      • HTTP: 8123 (सादा) / 8443 (TLS) — इस सर्वर और ClickHouse Cloud HTTPS द्वारा उपयोग किया जाता है
      • नेटिव TCP (यहाँ समर्थित नहीं): 9000 (सादा) / 9440 (TLS) — clickhouse-client द्वारा उपयोग किया जाता है
    • यदि सर्वर Port 9000 is for clickhouse-client program के साथ प्रतिक्रिया करता है, तो आप नेटिव प्रोटोकॉल की ओर इंगित हैं; HTTP पोर्ट पर स्विच करें (8123/8443 या आपके डिप्लॉयमेंट का HTTP मैपिंग)
  • CLICKHOUSE_ROLE: प्रमाणीकरण के लिए उपयोग करने के लिए ClickHouse भूमिका
    • डिफ़ॉल्ट: कोई नहीं
    • इसे सेट करें यदि आपके उपयोगकर्ता को एक विशिष्ट भूमिका की आवश्यकता है
  • CLICKHOUSE_SECURE: ClickHouse डेटाबेस कनेक्शन के लिए HTTPS सक्षम करें (MCP क्लाइंट के लिए नहीं)
    • डिफ़ॉल्ट: "true"
    • "false" पर केवल तभी सेट करें जब MCP सर्वर ClickHouse तक सादे HTTP पर पहुँचता है (पोर्ट 8123 पर स्थानीय Docker Compose के लिए विशिष्ट)
    • ClickHouse Cloud और किसी भी HTTPS डेटाबेस एंडपॉइंट के लिए "true" छोड़ें—भले ही MCP सर्वर स्वयं HTTP, stdio, या एक इनग्रेस के माध्यम से उजागर हो जो TLS को अलग से समाप्त करता है
    • इस फ़्लैग को डेटाबेस पोर्ट के साथ बेमेल करना (जैसे पोर्ट 8443 के विरुद्ध CLICKHOUSE_SECURE=false) एक लगातार सेटअप गलती है और आमतौर पर स्पष्ट "गलत स्कीम" संदेश के बजाय भ्रामक HTTP क्लाइंट त्रुटियों के रूप में प्रकट होता है
  • CLICKHOUSE_VERIFY: ClickHouse HTTPS कनेक्शन के लिए SSL प्रमाणपत्र सत्यापन सक्षम/अक्षम करें
    • डिफ़ॉल्ट: "true"
    • प्रमाणपत्र सत्यापन अक्षम करने के लिए "false" पर सेट करें (उत्पादन के लिए अनुशंसित नहीं)
    • TLS प्रमाणपत्र: पैकेज स्टार्टअप पर truststore.inject_into_ssl() के माध्यम से आपके ऑपरेटिंग सिस्टम ट्रस्ट स्टोर का उपयोग करता है। यदि MCP_CLICKHOUSE_TRUSTSTORE_DISABLE=1 के साथ इंजेक्शन अक्षम किया गया है या विफल हो जाता है, तो Python की डिफ़ॉल्ट SSL हैंडलिंग का उपयोग किया जाता है।
  • MCP_CLICKHOUSE_TRUSTSTORE_DISABLE: TLS के लिए प्रक्रिया-व्यापी ऑपरेटिंग सिस्टम ट्रस्ट स्टोर एकीकरण अक्षम करें
    • डिफ़ॉल्ट: अनसेट (ट्रस्ट स्टोर एकीकरण सक्षम है)
    • स्टार्टअप से पहले बिल्कुल "1" पर सेट करें ताकि truststore.inject_into_ssl() को छोड़ दिया जाए और Python की डिफ़ॉल्ट SSL प्रमाणपत्र हैंडलिंग का उपयोग किया जाए। अन्य मान एकीकरण को अक्षम नहीं करते हैं।
    • यह प्रमाणपत्र सत्यापन को अक्षम नहीं करता है। CLICKHOUSE_VERIFY अभी भी ClickHouse HTTPS कनेक्शन के लिए सत्यापन को नियंत्रित करता है।
  • CLICKHOUSE_CA_CERT: ClickHouse HTTPS कनेक्शन के लिए PEM CA प्रमाणपत्र बंडल का पथ
    • डिफ़ॉल्ट: कोई नहीं (ऑपरेटिंग सिस्टम ट्रस्ट स्टोर का उपयोग करता है जब तक कि ट्रस्टस्टोर इंजेक्शन अक्षम या विफल न हो)
    • इसे अकेले उपयोग करें जब एक ClickHouse सर्वर या निजी प्रॉक्सी एक निजी CA द्वारा हस्ताक्षरित प्रमाणपत्र प्रस्तुत करता है। यह सर्वर प्रमाणपत्र सत्यापन को बदलता है और क्लाइंट प्रमाणपत्र प्रमाणीकरण सक्षम नहीं करता है।
    • CLICKHOUSE_SECURE=true और CLICKHOUSE_VERIFY=true की आवश्यकता है
  • CLICKHOUSE_CLIENT_CERT: ClickHouse HTTPS कनेक्शन के लिए PEM क्लाइंट प्रमाणपत्र का पथ
    • डिफ़ॉल्ट: कोई नहीं
    • फ़ाइल में निजी कुंजी भी हो सकती है। अन्यथा CLICKHOUSE_CLIENT_CERT_KEY सेट करें।
    • ClickHouse उपयोगकर्ता अभी भी CLICKHOUSE_USER से आता है।
  • CLICKHOUSE_CLIENT_CERT_KEY: CLICKHOUSE_CLIENT_CERT के लिए PEM निजी कुंजी का पथ
    • डिफ़ॉल्ट: कोई नहीं
    • वैकल्पिक जब निजी कुंजी क्लाइंट प्रमाणपत्र फ़ाइल में शामिल होती है
    • CLICKHOUSE_CLIENT_CERT के बिना उपयोग नहीं किया जा सकता
  • CLICKHOUSE_TLS_MODE: clickhouse-connect CLICKHOUSE_CLIENT_CERT का उपयोग कैसे करता है
    • डिफ़ॉल्ट: कोई नहीं, जो क्लाइंट प्रमाणपत्र सेट होने पर "mutual" के रूप में व्यवहार करता है
    • "mutual": ClickHouse X.509 उपयोगकर्ता प्रमाणीकरण के लिए क्लाइंट प्रमाणपत्र का उपयोग करें। CLICKHOUSE_PASSWORD वैकल्पिक है और नहीं भेजा जाता है।
    • "proxy": क्लाइंट प्रमाणपत्र को TLS-समाप्त करने वाले प्रॉक्सी को प्रस्तुत करें, फिर ClickHouse Basic प्रमाणीकरण का उपयोग करें। CLICKHOUSE_PASSWORD आवश्यक है।
    • "strict": क्लाइंट प्रमाणपत्र प्रस्तुत करें क्योंकि ClickHouse सर्वर को TLS परत पर एक की आवश्यकता होती है, फिर ClickHouse Basic प्रमाणीकरण का उपयोग करें। CLICKHOUSE_PASSWORD आवश्यक है। यह मोड सर्वर प्रमाणपत्र सत्यापन को मजबूत नहीं करता है। CLICKHOUSE_VERIFY उस सत्यापन को नियंत्रित करता है।
    • clickhouse-connect "proxy" और "strict" को समान रूप से मानता है। दोनों नाम इरादे का दस्तावेजीकरण करते हैं।
    • मान ट्रिम किए जाते हैं और केस-असंवेदनशील होते हैं। एक रिक्त मान अनसेट के रूप में माना जाता है। अन्य मान ClickHouse क्लाइंट बनाने से पहले, पहले ClickHouse टूल कॉल या /health प्रोब पर अस्वीकार कर दिए जाते हैं।
    • CLICKHOUSE_CLIENT_CERT की आवश्यकता है। सभी क्लाइंट प्रमाणपत्र विकल्पों को CLICKHOUSE_SECURE=true की आवश्यकता होती है।
  • CLICKHOUSE_SERVER_HOST_NAME: ClickHouse कनेक्शन पर SNI ओवरराइड और प्रमाणपत्र सत्यापन के लिए सर्वर होस्टनाम
    • डिफ़ॉल्ट: कोई नहीं (कनेक्शन होस्टनाम का उपयोग करता है)
    • यह प्रॉक्सी या लोड बैलेंसर के माध्यम से कनेक्ट करते समय उपयोगी है जहाँ प्रमाणपत्र होस्टनाम कनेक्शन होस्टनाम से भिन्न होता है। सेट होने पर, यह होस्टनाम TLS हैंडशेक के दौरान SNI (सर्वर नाम संकेत) और प्रमाणपत्र होस्टनाम सत्यापन दोनों के लिए उपयोग किया जाएगा।
  • CLICKHOUSE_PROXY_PATH: ClickHouse HTTP एंडपॉइंट के लिए URL पथ उपसर्ग
    • डिफ़ॉल्ट: कोई नहीं
    • इसे सेट करें जब ClickHouse HTTP इंटरफ़ेस एक रिवर्स प्रॉक्सी के पीछे पथ उपसर्ग के तहत उजागर होता है (उदाहरण के लिए, /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"
    • केवल chDB का उपयोग करते समय ClickHouse टूल अक्षम करने के लिए "false" पर सेट करें
  • CLICKHOUSE_ALLOW_WRITE_ACCESS: ClickHouse के विरुद्ध लेखन संचालन (DDL और DML) की अनुमति दें
    • डिफ़ॉल्ट: "false"
    • गैर-विनाशकारी DDL और DML (CREATE, INSERT, ALTER ADD COLUMN) की अनुमति देने के लिए "true" पर सेट करें। विनाशकारी स्टेटमेंट को अतिरिक्त रूप से 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 भी सेट हो
    • यह गेट MCP सर्वर में एक सर्वोत्तम-प्रयास दुर्घटना रक्षक है, सुरक्षा सीमा नहीं। वास्तविक प्रवर्तन के लिए ClickHouse उपयोगकर्ता के अनुदान प्रतिबंधित करें (देखें विनाशकारी संचालन सुरक्षा)
ClickHouse TLS प्रमाणपत्र फ़ाइलें

प्रमाणपत्र चर में फ़ाइल पथ होते हैं, PEM सामग्री नहीं। mcp-clickhouse इन पथों को clickhouse-connect को पास करता है। Docker या Kubernetes के लिए, प्रमाणपत्र और निजी कुंजी को केवल-पठनीय फ़ाइलों के रूप में माउंट करें और कंटेनर के अंदर उनके पथ का उपयोग करें। एक निजी कुंजी को छवि में बेक न करें, इसे स्रोत नियंत्रण में प्रतिबद्ध न करें, या इसकी सामग्री को पर्यावरण चर में न डालें।

mutual मोड में, कॉन्फ़िगर किया गया क्लाइंट प्रमाणपत्र इस mcp-clickhouse प्रक्रिया को CLICKHOUSE_USER के रूप में पहचानता है। यह इनबाउंड MCP क्लाइंट को प्रमाणित नहीं करता है या उनकी पहचान ClickHouse को पास नहीं करता है। MCP ट्रांसपोर्ट प्रमाणीकरण अलग से कॉन्फ़िगर करें।

जब तत्काल रोटेशन या रद्दीकरण की आवश्यकता हो, तो उसी पथ पर प्रमाणपत्र या कुंजी बदलने के बाद mcp-clickhouse को पुनरारंभ करें। कैश्ड क्लाइंट मौजूदा TLS कनेक्शन बनाए रख सकते हैं, और कैश फ़ाइल सामग्री या संशोधन समय को ट्रैक नहीं करता है।

ClickHouse Cloud डेटाबेस उपयोगकर्ताओं के लिए X.509 क्लाइंट प्रमाणपत्र प्रमाणीकरण का समर्थन नहीं करता है। ClickHouse Cloud के लिए CLICKHOUSE_USER और CLICKHOUSE_PASSWORD का उपयोग करें। एक 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 परिवहन का चयन करता है और एक चेतावनी लॉग करता है। नई तैनाती में Streamable HTTP के लिए "http" का उपयोग करें।
  • CLICKHOUSE_MCP_BIND_HOST: HTTP या SSE परिवहन का उपयोग करते समय MCP सर्वर को बाइंड करने के लिए होस्ट
    • डिफ़ॉल्ट: "127.0.0.1"
    • सभी नेटवर्क इंटरफेस से बाइंड करने के लिए "0.0.0.0" पर सेट करें (Docker या दूरस्थ पहुंच के लिए उपयोगी)
    • केवल तब उपयोग किया जाता है जब परिवहन "http" या "sse" हो — CLICKHOUSE_HOST से संबंधित नहीं
  • CLICKHOUSE_MCP_BIND_PORT: HTTP या SSE परिवहन का उपयोग करते समय MCP सर्वर को बाइंड करने के लिए पोर्ट
    • डिफ़ॉल्ट: "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 परिवहन के लिए स्थिर बियरर टोकन
    • डिफ़ॉल्ट: कोई नहीं
    • HTTP/SSE परिवहन के लिए CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH, या CLICKHOUSE_MCP_AUTH_DISABLED=true में से एक आवश्यक है
    • uuidgen या openssl rand -hex 32 का उपयोग करके उत्पन्न करें
    • क्लाइंट को यह टोकन Authorization: Bearer <token> हेडर में भेजना चाहिए
  • FASTMCP_SERVER_AUTH: FastMCP auth provider को प्रमाणीकरण सौंपें
    • डिफ़ॉल्ट: कोई नहीं
    • मान AuthProvider उपवर्ग का पूर्ण क्लास पथ है, जैसे fastmcp.server.auth.providers.azure.AzureProvider या fastmcp.server.auth.providers.google.GoogleProvider
    • सेट होने पर, mcp-clickhouse मौजूदा FASTMCP_SERVER_AUTH_* पर्यावरण चर से प्रदाता लोड करता है; इस मोड में CLICKHOUSE_MCP_AUTH_TOKEN को अनसेट छोड़ें
    • कस्टम प्रदाताओं को पर्यावरण-व्युत्पन्न कंस्ट्रक्टर तर्क नहीं मिलते और उन्हें बिना-तर्क निर्माण का समर्थन करना चाहिए
    • FastMCP 4 अब Supabase HS256 सत्यापन का समर्थन नहीं करता। 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 सर्वर उत्तर देता है
    • लूपबैक बाइंड के लिए डिफ़ॉल्ट: 127.0.0.1, localhost, और [::1] के बेयर और किसी-भी-पोर्ट रूप
    • सेट होने पर, मान में कम से कम एक Host प्रविष्टि होनी चाहिए।
    • एक ठोस गैर-लूपबैक बाइंड पता उस पते और कॉन्फ़िगर किए गए पोर्ट पर डिफ़ॉल्ट होता है। 0.0.0.0 या :: जैसा वाइल्डकार्ड बाइंड एक स्पष्ट गैर-रिक्त मान की आवश्यकता रखता है क्योंकि सार्वजनिक Host का अनुमान नहीं लगाया जा सकता।
    • Host सत्यापन DNS रीबाइंडिंग के खिलाफ गहराई में सुरक्षा है। नीचे ओरिजिन सत्यापन 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 मिलता है। /health के लिए GET और HEAD अनुरोध Host और Origin सत्यापन से मुक्त हैं ताकि ऑर्केस्ट्रेटर प्रोब काम करते रहें।
    • रिवर्स प्रॉक्सी के पीछे, मूल Host हेडर को संरक्षित करना पसंद करें। आप इसके बजाय प्रॉक्सी द्वारा भेजे गए अपस्ट्रीम Host मान को सूचीबद्ध कर सकते हैं। जब fastmcp run जैसा लॉन्चर दूरस्थ पहुंच के लिए बाइंड पता ओवरराइड करता है तो एक स्पष्ट सूची सेट करें।
    • mcp-clickhouse FastMCP के अलग Host और Origin गार्ड को बंद करने के लिए बाध्य करता है। 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 अनदेखा किया जाता है। X-Forwarded-For और X-Forwarded-Proto की मौजूदा Uvicorn हैंडलिंग अपरिवर्तित है।
    • प्रविष्टियाँ 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: HTTP/SSE पर स्वीकृत अल्पविराम से अलग Origin हेडर मान
    • डिफ़ॉल्ट: कोई नहीं, जो हर अनुरोध को अस्वीकार करता है जो Origin हेडर रखता है
    • MCP को HTTP/SSE परिवहन कनेक्शन के लिए Origin सत्यापन की आवश्यकता होती है। बिना Origin के अनुरोध स्वीकार किए जाते हैं क्योंकि गैर-ब्राउज़र MCP क्लाइंट सामान्यतः इसे छोड़ देते हैं। एक गैर-मेल खाता Origin 403 Forbidden प्राप्त करता है। /health एंडपॉइंट ऊपर वर्णित अनुसार मुक्त है।
    • प्रविष्टियाँ सटीक (http://localhost:3000) हैं या किसी भी पोर्ट को स्वीकार करती हैं (http://localhost:*)। होस्ट की तरह, किसी-भी-पोर्ट रूप केवल उन ओरिजिन से मेल खाता है जो पोर्ट रखते हैं; एक मानक-पोर्ट ओरिजिन (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 या दोहरे-स्टैक बाइंड पर, IPv4 प्रॉक्सी IPv4-मैप किए गए पते जैसे ::ffff:10.20.0.8 के रूप में दिखाई दे सकते हैं; ये स्वचालित रूप से IPv4 प्रविष्टियों से मेल खाते हैं। Envoy का append_x_forwarded_host मौजूदा X-Forwarded-Host में जोड़ता है बजाय इसे अधिलेखित करने के, एक अल्पविराम से अलग सूची उत्पन्न करता है जो अस्वीकार कर दी जाती है, इसलिए भरोसेमंद हॉप को हेडर अधिलेखित करने के लिए कॉन्फ़िगर करें। स्रोत NAT के साथ Kubernetes पर (उदाहरण के लिए externalTrafficPolicy: Cluster) देखा गया पीयर प्रॉक्सी पॉड के बजाय नोड IP हो सकता है, इसलिए उचित रूप से पॉड या नोड CIDR पर भरोसा करें; ingress-nginx स्वयं Host और X-Forwarded-Host दोनों अधिलेखित करता है।

मिडलवेयर चर

  • MCP_MIDDLEWARE_MODULE: MCP सर्वर में इंजेक्ट करने के लिए कस्टम मिडलवेयर वाला Python मॉड्यूल नाम
    • डिफ़ॉल्ट: कोई नहीं (कोई मिडलवेयर लोड नहीं)
    • अपने मिडलवेयर मॉड्यूल के मॉड्यूल नाम (बिना .py एक्सटेंशन) पर सेट करें
    • मॉड्यूल को एक setup_middleware(mcp) फ़ंक्शन प्रदान करना चाहिए
    • विवरण और उदाहरण के लिए Custom Middleware देखें

chDB चर

  • CHDB_ENABLED: chDB कार्यक्षमता सक्षम/अक्षम करें
    • डिफ़ॉल्ट: "false"
    • chDB टूल सक्षम करने के लिए "true" पर सेट करें
    • वैकल्पिक एक्स्ट्रा स्थापित करने की आवश्यकता है: mcp-clickhouse[chdb]
  • CHDB_DATA_PATH: chDB डेटा निर्देशिका का पथ
    • डिफ़ॉल्ट: ":memory:" (इन-मेमोरी डेटाबेस)
    • इन-मेमोरी डेटाबेस के लिए :memory: का उपयोग करें
    • स्थायी भंडारण के लिए फ़ाइल पथ का उपयोग करें (जैसे, /path/to/chdb/data)

सामान्य कॉन्फ़िगरेशन गलतियाँ

  • CLICKHOUSE_SECURE बनाम MCP / ingress TLS — CLICKHOUSE_SECURE बंद करना क्योंकि MCP सर्वर Kubernetes ingress, रिवर्स प्रॉक्सी के पीछे है, या सादे HTTP पर पहुंचा जाता है, डेटाबेस TLS अक्षम नहीं करता; यह केवल बदलता है कि यह प्रक्रिया ClickHouse से कैसे जुड़ती है। डेटाबेस क्लाइंट सेटिंग्स से अलग ingress TLS कॉन्फ़िगर करें।
  • नेटिव प्रोटोकॉल पोर्ट — CLICKHOUSE_PORT को ClickHouse के HTTP इंटरफेस (डिफ़ॉल्ट रूप से 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

ClickHouse X.509 क्लाइंट प्रमाणपत्र प्रमाणीकरण के लिए:

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

Use CLICKHOUSE_TLS_MODE=proxy instead when a TLS-terminating proxy requires the client certificate and ClickHouse still uses Basic authentication.

For chDB only (in-memory):

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

For chDB with persistent storage:

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

For MCP Inspector or remote access with 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

For local development with HTTP transport (authentication disabled):

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

When using HTTP transport, the server will run on the configured port (default 8000). For example, with the above configuration:

  • MCP endpoint: http://localhost:8000/mcp
  • Health check: http://localhost:8000/health

You can set these variables in your environment, in a .env file, or in the Claude Desktop configuration:

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

Note: The bind host and port settings are only used when transport is set to "http" or "sse".

Running tests

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 Overview

YouTube