ClickHouse

आधिकारिक

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

GitHub

839

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

केवल-पढ़ने योग्य SQL क्वेरी चलाएँ — सहायक से अपने ClickHouse क्लस्टर पर run_query का उपयोग करके कोई भी SELECT क्वेरी निष्पादित करने के लिए कहें।
डेटाबेस और तालिकाओं की सूची बनाएँ — list_databases के साथ सभी डेटाबेसों को सूचीबद्ध करके या list_tables के साथ किसी विशिष्ट डेटाबेस में तालिकाओं के माध्यम से पृष्ठांकन करके अपनी स्कीमा का अन्वेषण करें।
chDB के माध्यम से सीधे फ़ाइलों और URL से क्वेरी करें — स्थानीय फ़ाइलों या दूरस्थ डेटा स्रोतों पर SQL चलाने के लिए run_chdb_select_query का उपयोग करें, बिना उन्हें पहले ClickHouse में लोड किए।
लेखन और विनाशकारी संचालन को नियंत्रित करें — DDL/DML के लिए CLICKHOUSE_ALLOW_WRITE_ACCESS सक्षम करें, और वैकल्पिक रूप से AI-सहायता प्राप्त सत्रों के दौरान DROP या TRUNCATE स्टेटमेंट की अनुमति देने के लिए CLICKHOUSE_ALLOW_DROP सक्षम करें।

दस्तावेज़

ClickHouse MCP सर्वर

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

विशेषताएँ

ClickHouse उपकरण

run_query
- अपने ClickHouse क्लस्टर पर SQL क्वेरीज़ निष्पादित करें।
- इनपुट: query (स्ट्रिंग): निष्पादित की जाने वाली SQL क्वेरी।
- क्वेरीज़ डिफ़ॉल्ट रूप से केवल-पठन मोड में चलती हैं (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), लेकिन यदि आवश्यक हो तो लेखन को स्पष्ट रूप से सक्षम किया जा सकता है।
list_databases
- अपने ClickHouse क्लस्टर पर सभी डेटाबेस सूचीबद्ध करें।
list_tables
- पृष्ठांकन के साथ किसी डेटाबेस में तालिकाएँ सूचीबद्ध करें।
- आवश्यक इनपुट: database (स्ट्रिंग)।
- वैकल्पिक इनपुट:
  - like / not_like (स्ट्रिंग): तालिका नामों पर LIKE या NOT LIKE फ़िल्टर लागू करें।
  - page_token (स्ट्रिंग): अगले पृष्ठ को प्राप्त करने के लिए पिछले कॉल द्वारा लौटाया गया टोकन।
  - page_size (int, डिफ़ॉल्ट 50): प्रति पृष्ठ लौटाई जाने वाली तालिकाओं की संख्या।
  - include_detailed_columns (bool, डिफ़ॉल्ट true): जब false, तो पूर्ण create_table_query रखते हुए हल्की प्रतिक्रियाओं के लिए स्तंभ मेटाडेटा छोड़ देता है।
- प्रतिक्रिया आकार:
  - tables: वर्तमान पृष्ठ के लिए तालिका ऑब्जेक्ट की सरणी।
  - next_page_token: अगला पृष्ठ प्राप्त करने के लिए इस मान को वापस पास करें, या null जब कोई और तालिकाएँ न हों।
  - total_tables: आपूर्ति किए गए फ़िल्टर से मेल खाने वाली तालिकाओं की कुल संख्या।

chDB उपकरण

run_chdb_select_query
- chDB के एम्बेडेड ClickHouse इंजन का उपयोग करके SQL क्वेरीज़ निष्पादित करें।
- इनपुट: query (स्ट्रिंग): निष्पादित की जाने वाली SQL क्वेरी।
- ETL प्रक्रियाओं के बिना विभिन्न स्रोतों (फ़ाइलें, URL, डेटाबेस) से सीधे डेटा क्वेरी करें।
- वैकल्पिक chdb अतिरिक्त की आवश्यकता है: pip install 'mcp-clickhouse[chdb]'

स्वास्थ्य जाँच समापन बिंदु

HTTP या SSE परिवहन के साथ चलते समय, /health पर एक स्वास्थ्य जाँच समापन बिंदु उपलब्ध है। यह समापन बिंदु:

200 OK लौटाता है (मुख्य भाग: OK) यदि सर्वर स्वस्थ है और ClickHouse से कनेक्ट हो सकता है
503 Service Unavailable लौटाता है एक सामान्य त्रुटि संदेश के साथ यदि सर्वर ClickHouse से कनेक्ट नहीं हो सकता

समापन बिंदु जानबूझकर अप्रमाणीकृत है ताकि ऑर्केस्ट्रेटर जांच (जैसे, कुबेरनेट्स लाइवनेस/रेडीनेस, लोड बैलेंसर) बिना क्रेडेंशियल के उस तक पहुँच सकें। प्रतिक्रिया मुख्य भाग जानबूझकर न्यूनतम है ताकि बैकएंड संस्करण स्ट्रिंग या त्रुटि विवरण लीक होने से बचा जा सके; सर्वर लॉग के माध्यम से विफलताओं को डीबग करें।

उदाहरण:

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 परिवहन के लिए इनमें से कोई भी कॉन्फ़िगर नहीं किया गया है तो स्टार्टअप विफल हो जाता है।

प्रमाणीकरण सेट अप करना

एक सुरक्षित टोकन उत्पन्न करें (कोई भी यादृच्छिक स्ट्रिंग हो सकती है):
```
# Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32
```
टोकन के साथ सर्वर को कॉन्फ़िगर करें:
```
export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"
```
अनुरोधों में टोकन शामिल करने के लिए अपने MCP क्लाइंट को कॉन्फ़िगर करें:

HTTP/SSE परिवहन के साथ Claude Desktop के लिए:
```
{
  "mcpServers": {
    "mcp-clickhouse": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "Authorization": "Bearer your-generated-token"
      }
    }
  }
}
```
नोट: /health समापन बिंदु जानबूझकर अप्रमाणीकृत है (ऊपर स्वास्थ्य जाँच समापन बिंदु देखें)। यह सत्यापित करने के लिए कि बियरर-टोकन प्रमाणीकरण वास्तव में अप्रमाणीकृत अनुरोधों को अस्वीकार कर रहा है, MCP समापन बिंदु पर ही प्रहार करें, जैसे MCP इंस्पेक्टर के साथ, या Authorization हेडर के साथ और बिना /mcp पर 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>"

प्रदाताओं और उनके आवश्यक पर्यावरण चर की पूरी सूची के लिए FastMCP दस्तावेज़ देखें।

विकास मोड (प्रमाणीकरण अक्षम करना)

केवल स्थानीय विकास और परीक्षण के लिए, आप सेट करके प्रमाणीकरण अक्षम कर सकते हैं:

export CLICKHOUSE_MCP_AUTH_DISABLED=true

चेतावनी: इसका उपयोग केवल स्थानीय विकास के लिए करें। जब सर्वर किसी भी नेटवर्क के संपर्क में हो तो प्रमाणीकरण अक्षम न करें।

कॉन्फ़िगरेशन

यह MCP सर्वर ClickHouse और chDB दोनों का समर्थन करता है। आप अपनी आवश्यकताओं के अनुसार या तो एक या दोनों को सक्षम कर सकते हैं।

Claude Desktop कॉन्फ़िगरेशन फ़ाइल खोलें जो यहाँ स्थित है:
- macOS पर: ~/Library/Application Support/Claude/claude_desktop_config.json
- विंडोज पर: %APPDATA%/Claude/claude_desktop_config.json
निम्नलिखित जोड़ें:

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

अपनी स्वयं की ClickHouse सेवा को इंगित करने के लिए पर्यावरण चर अपडेट करें।

या, यदि आप इसे ClickHouse SQL Playground के साथ आज़माना चाहते हैं, तो आप निम्नलिखित कॉन्फ़िगरेशन का उपयोग कर सकते हैं:

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

chDB (एम्बेडेड ClickHouse इंजन) के लिए, निम्नलिखित कॉन्फ़िगरेशन जोड़ें:

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

आप एक साथ ClickHouse और chDB दोनों को भी सक्षम कर सकते हैं:

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

uv के लिए कमांड प्रविष्टि का पता लगाएँ और इसे uv निष्पादन योग्य के पूर्ण पथ से बदलें। यह सुनिश्चित करता है कि सर्वर शुरू करते समय uv का सही संस्करण उपयोग किया जाए। मैक पर, आप which uv का उपयोग करके यह पथ पा सकते हैं।
परिवर्तनों को लागू करने के लिए Claude Desktop को पुनरारंभ करें।

वैकल्पिक लेखन पहुँच

डिफ़ॉल्ट रूप से, यह MCP केवल-पठन क्वेरीज़ लागू करता है ताकि अन्वेषण के दौरान आकस्मिक उत्परिवर्तन न हो सकें। DDL या INSERT/UPDATE कथनों की अनुमति देने के लिए, CLICKHOUSE_ALLOW_WRITE_ACCESS पर्यावरण चर को true पर सेट करें। यदि ClickHouse इंस्टेंस स्वयं लेखन की अनुमति नहीं देता है तो सर्वर केवल-पठन मोड लागू करना जारी रखता है।

विनाशकारी संचालन सुरक्षा

यहां तक कि जब लेखन पहुँच सक्षम हो (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), विनाशकारी संचालन (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) के लिए सुरक्षा के लिए एक अतिरिक्त ऑप्ट-इन ध्वज की आवश्यकता होती है। यह AI अन्वेषण के दौरान आकस्मिक डेटा विलोपन को रोकता है।

विनाशकारी संचालन सक्षम करने के लिए, दोनों ध्वज सेट करें:

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

यह दो-स्तरीय दृष्टिकोण सुनिश्चित करता है कि आकस्मिक ड्रॉप बहुत कठिन हैं:

लेखन संचालन (INSERT, UPDATE, CREATE) के लिए CLICKHOUSE_ALLOW_WRITE_ACCESS=true की आवश्यकता होती है
विनाशकारी संचालन (DROP, TRUNCATE) के लिए अतिरिक्त रूप से CLICKHOUSE_ALLOW_DROP=true की आवश्यकता होती है

uv के बिना चलाना (सिस्टम Python का उपयोग करके)

यदि आप uv के बजाय सिस्टम Python स्थापना का उपयोग करना पसंद करते हैं, तो आप PyPI से पैकेज स्थापित कर सकते हैं और इसे सीधे चला सकते हैं:

pip का उपयोग करके पैकेज स्थापित करें:
```
python3 -m pip install mcp-clickhouse
```
chDB समर्थन भी स्थापित करने के लिए:
```
python3 -m pip install 'mcp-clickhouse[chdb]'
```
नवीनतम संस्करण में अपग्रेड करने के लिए:
```
python3 -m pip install --upgrade mcp-clickhouse
```
सीधे 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",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

वैकल्पिक रूप से, आप सीधे स्थापित स्क्रिप्ट का उपयोग कर सकते हैं:

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

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

Python निष्पादन योग्य के लिए which python3
स्थापित स्क्रिप्ट के लिए which mcp-clickhouse

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

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

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

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

MCP_MIDDLEWARE_MODULE पर्यावरण चर को मॉड्यूल नाम पर सेट करें (.py एक्सटेंशन के बिना):

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}

सुनिश्चित करें कि आपका मिडलवेयर मॉड्यूल 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 mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY

ctx = get_context()
ctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, {
    "connect_timeout": 60,
    "send_receive_timeout": 120
})

यह गतिशील टाइमआउट समायोजन, किरायेदार-विशिष्ट रूटिंग, या प्रति-उपयोगकर्ता कनेक्शन सेटिंग्स जैसे उन्नत उपयोग के मामलों को सक्षम बनाता है।

विकास

test-services निर्देशिका में ClickHouse क्लस्टर शुरू करने के लिए docker compose up -d चलाएँ।
रिपॉजिटरी के रूट में एक .env फ़ाइल में निम्नलिखित चर जोड़ें।

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

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

निर्भरताएँ स्थापित करने के लिए uv sync चलाएँ। uv स्थापित करने के लिए यहाँ दिए गए निर्देशों का पालन करें। फिर source .venv/bin/activate करें।
MCP इंस्पेक्टर के साथ आसान परीक्षण के लिए, MCP सर्वर शुरू करने के लिए fastmcp dev mcp_clickhouse/mcp_server.py चलाएँ।

HTTP परिवहन और स्वास्थ्य जाँच समापन बिंदु के साथ परीक्षण करने के लिए:

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

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

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

पर्यावरण चर

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

समूह	चर	नियंत्रण
ClickHouse डेटाबेस कनेक्शन	`CLICKHOUSE_HOST`, `CLICKHOUSE_PORT`, `CLICKHOUSE_SECURE`, `CLICKHOUSE_VERIFY`, …	यह MCP सर्वर HTTP इंटरफ़ेस के माध्यम से आपके ClickHouse क्लस्टर से कैसे जुड़ता है
MCP सर्वर / परिवहन	`CLICKHOUSE_MCP_`, `FASTMCP_SERVER_AUTH`, `FASTMCP_SERVER_AUTH_`	MCP परिवहन, प्रमाणीकरण, और क्वेरी-उपकरण निष्पादन सीमाएँ
मिडलवेयर / chDB	`MCP_MIDDLEWARE_MODULE`, `CHDB_*`	वैकल्पिक एक्सटेंशन

[!महत्वपूर्ण] CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, और CLICKHOUSE_PORT जैसे चर केवल ClickHouse डेटाबेस कनेक्शन पर लागू होते हैं। वे MCP प्रोटोकॉल समापन बिंदु के लिए TLS, पोर्ट या प्रमाणीकरण को कॉन्फ़िगर नहीं करते हैं।

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

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

ये वेरिएबल clickhouse-connect HTTP क्लाइंट और run_query, list_databases, और list_tables जैसे ClickHouse-समर्थित टूल्स के व्यवहार को कॉन्फ़िगर करते हैं।

आवश्यक वेरिएबल

CLICKHOUSE_HOST: आपके ClickHouse सर्वर का होस्टनाम (डेटाबेस एंडपॉइंट, MCP सर्वर बाइंड पता नहीं)
CLICKHOUSE_USER: ClickHouse प्रमाणीकरण के लिए उपयोगकर्ता नाम
CLICKHOUSE_PASSWORD: ClickHouse प्रमाणीकरण के लिए पासवर्ड

[!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 सर्वर सादे HTTP पर ClickHouse तक पहुँचता है (पोर्ट 8123 पर स्थानीय Docker Compose के लिए विशिष्ट)
- ClickHouse Cloud और किसी भी HTTPS डेटाबेस एंडपॉइंट के लिए "true" छोड़ दें—भले ही MCP सर्वर स्वयं HTTP, stdio, या एक इन्ग्रेस के माध्यम से उजागर हो जो TLS को अलग से समाप्त करता है
- इस फ़्लैग को डेटाबेस पोर्ट के साथ बेमेल करना (जैसे CLICKHOUSE_SECURE=false पोर्ट 8443 के विरुद्ध) एक सामान्य सेटअप गलती है और आमतौर पर एक स्पष्ट "गलत स्कीम" संदेश के बजाय भ्रामक HTTP क्लाइंट त्रुटियों के रूप में सामने आती है
CLICKHOUSE_VERIFY: ClickHouse HTTPS कनेक्शन के लिए SSL प्रमाणपत्र सत्यापन सक्षम/अक्षम करें
- डिफ़ॉल्ट: "true"
- प्रमाणपत्र सत्यापन अक्षम करने के लिए "false" पर सेट करें (उत्पादन के लिए अनुशंसित नहीं)
- TLS प्रमाणपत्र: पैकेज truststore के माध्यम से TLS प्रमाणपत्र सत्यापन के लिए आपके ऑपरेटिंग सिस्टम ट्रस्ट स्टोर का उपयोग करता है। हम उचित प्रमाणपत्र हैंडलिंग सुनिश्चित करने के लिए स्टार्टअप पर truststore.inject_into_ssl() कॉल करते हैं। पायथन का डिफ़ॉल्ट SSL व्यवहार केवल तभी फ़ॉलबैक के रूप में उपयोग किया जाता है जब कोई अप्रत्याशित त्रुटि होती है।
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_DATABASE: उपयोग करने के लिए डिफ़ॉल्ट ClickHouse डेटाबेस
- डिफ़ॉल्ट: कोई नहीं (सर्वर डिफ़ॉल्ट का उपयोग करता है)
- किसी विशिष्ट डेटाबेस से स्वचालित रूप से कनेक्ट करने के लिए इसे सेट करें
CLICKHOUSE_ENABLED: ClickHouse डेटाबेस टूल्स सक्षम/अक्षम करें
- डिफ़ॉल्ट: "true"
- केवल chDB का उपयोग करते समय ClickHouse टूल्स को अक्षम करने के लिए "false" पर सेट करें
CLICKHOUSE_ALLOW_WRITE_ACCESS: ClickHouse के विरुद्ध राइट ऑपरेशन (DDL और DML) की अनुमति दें
- डिफ़ॉल्ट: "false"
- DDL (CREATE, ALTER, DROP) और DML (INSERT, UPDATE, DELETE) ऑपरेशन की अनुमति देने के लिए "true" पर सेट करें
- अक्षम होने पर (डिफ़ॉल्ट), डेटा संशोधनों को रोकने के लिए क्वेरीज़ readonly=1 सेटिंग के साथ चलती हैं
CLICKHOUSE_ALLOW_DROP: विनाशकारी ऑपरेशन (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) की अनुमति दें
- डिफ़ॉल्ट: "false"
- केवल तभी प्रभावी होता है जब CLICKHOUSE_ALLOW_WRITE_ACCESS=true भी सेट हो
- विनाशकारी DROP और TRUNCATE ऑपरेशन को स्पष्ट रूप से अनुमति देने के लिए "true" पर सेट करें
- AI अन्वेषण के दौरान आकस्मिक डेटा विलोपन को रोकने के लिए यह एक सुरक्षा सुविधा है

MCP सर्वर और ट्रांसपोर्ट

ये वेरिएबल MCP प्रक्रिया को ही नियंत्रित करते हैं, जिसमें ट्रांसपोर्ट, प्रमाणीकरण और क्वेरी-टूल निष्पादन सीमाएँ शामिल हैं। वे ऊपर दी गई ClickHouse डेटाबेस सेटिंग्स से स्वतंत्र हैं। HTTP/SSE ट्रांसपोर्ट के लिए प्रमाणीकरण भी देखें।

CLICKHOUSE_MCP_SERVER_TRANSPORT: MCP सर्वर के लिए ट्रांसपोर्ट विधि सेट करता है
- डिफ़ॉल्ट: "stdio"
- मान्य विकल्प: "stdio", "http", "sse"। यह MCP इंस्पेक्टर जैसे टूल्स के साथ स्थानीय विकास के लिए उपयोगी है।
- stdio Claude Desktop के लिए विशिष्ट है; http/sse एक नेटवर्क श्रोता को उजागर करते हैं (नीचे बाइंड होस्ट/पोर्ट)
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 ... त्रुटियाँ देखते हैं तो इसे बढ़ाएँ
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 प्रदाता को प्रमाणीकरण सौंपें
- डिफ़ॉल्ट: कोई नहीं
- मान एक AuthProvider उपवर्ग का पूर्ण वर्ग पथ है, जैसे fastmcp.server.auth.providers.azure.AzureProvider या fastmcp.server.auth.providers.google.GoogleProvider
- सेट होने पर, FastMCP अपने स्वयं के FASTMCP_SERVER_AUTH_* पर्यावरण चर से प्रदाता को ऑटो-लोड करता है; इस मोड में CLICKHOUSE_MCP_AUTH_TOKEN को अनसेट छोड़ दें
CLICKHOUSE_MCP_AUTH_DISABLED: HTTP/SSE ट्रांसपोर्ट के लिए प्रमाणीकरण अक्षम करें
- डिफ़ॉल्ट: "false" (प्रमाणीकरण सक्षम है)
- केवल स्थानीय विकास/परीक्षण के लिए प्रमाणीकरण अक्षम करने के लिए "true" पर सेट करें
- चेतावनी: केवल स्थानीय विकास के लिए उपयोग करें। नेटवर्क के संपर्क में आने पर अक्षम न करें

मिडलवेयर वेरिएबल

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

chDB वेरिएबल

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

सामान्य कॉन्फ़िगरेशन नुकसान

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

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

केवल chDB (इन-मेमोरी) के लिए:

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

स्थायी भंडारण के साथ chDB के लिए:

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

HTTP ट्रांसपोर्ट के साथ MCP इंस्पेक्टर या रिमोट एक्सेस के लिए:

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
CLICKHOUSE_MCP_BIND_PORT=4200  # Custom port (default: 8000)
CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # One auth mode required for HTTP/SSE (or FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED=true)

HTTP ट्रांसपोर्ट के साथ स्थानीय विकास के लिए (प्रमाणीकरण अक्षम):

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

HTTP ट्रांसपोर्ट का उपयोग करते समय, सर्वर कॉन्फ़िगर किए गए पोर्ट (डिफ़ॉल्ट 8000) पर चलेगा। उदाहरण के लिए, उपरोक्त कॉन्फ़िगरेशन के साथ:

MCP एंडपॉइंट: http://localhost:4200/mcp
हेल्थ चेक: http://localhost:4200/health

आप इन वेरिएबल को अपने पर्यावरण में, एक .env फ़ाइल में, या Claude Desktop कॉन्फ़िगरेशन में सेट कर सकते हैं:

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

नोट: बाइंड होस्ट और पोर्ट सेटिंग्स का उपयोग केवल तब किया जाता है जब ट्रांसपोर्ट "http" या "sse" पर सेट हो।

परीक्षण चलाना

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

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