Couchbase

Couchbase MCP सर्वर

Couchbase MCP सर्वर एक स्व-होस्टेड मॉडल कॉन्टेक्स्ट प्रोटोकॉल (MCP) सर्वर है जो AI एजेंटों और LLM-संचालित सहायकों — Claude, Cursor, Windsurf, VS Code Copilot, और अन्य MCP क्लाइंट्स — को Couchbase क्लस्टरों में डेटा से जोड़ता है, चाहे वे Capella पर होस्ट किए गए हों या स्व-प्रबंधित हों। MCP एक खुला मानक है जो AI सहायकों को टूल कॉल करने और बाहरी डेटा स्रोतों से क्वेरी करने की अनुमति देता है; यह सर्वर Couchbase के लिए उस मानक को लागू करता है, ताकि एक AI एजेंट आपके क्लस्टर का निरीक्षण कर सके, SQL++ क्वेरी चला सके, दस्तावेज़ पढ़ और लिख सके, और हाथ से लिखे कोड के बजाय प्राकृतिक भाषा का उपयोग करके क्वेरी प्रदर्शन का विश्लेषण कर सके।

यह क्लस्टर हेल्थ, डेटा स्कीमा, की-वैल्यू, क्वेरी, और प्रदर्शन सहित श्रेणियों में टूल प्रदान करता है — केवल-पढ़ने के मोड (डिफ़ॉल्ट रूप से चालू) और सूक्ष्म-स्तरीय टूल अक्षमीकरण के माध्यम से सुरक्षा नियंत्रण के साथ, ताकि आप किसी AI एजेंट को अनजाने में लिखने के जोखिम के बिना अपने डेटा का अन्वेषण और क्वेरी करने दे सकें। यह STDIO और स्ट्रीमेबल HTTP ट्रांसपोर्ट दोनों का समर्थन करता है।

Couchbase MCP सर्वर को पायथन पैकेज इंडेक्स (PyPI) पैकेज और Docker के माध्यम से वितरित किया जाता है। Couchbase MCP सर्वर के लिए एंटरप्राइज़ समर्थन Couchbase AI डेटा प्लेन को लाइसेंस देकर उपलब्ध है, जो Couchbase एजेंट मेमोरी और Couchbase एजेंट कैटलॉग के उपयोग और एंटरप्राइज़ समर्थन का भी अधिकार देता है।

पूर्ण दस्तावेज़ीकरण के लिए, mcp-server.couchbase.com पर जाएँ।

पूर्ण दस्तावेज़ीकरण के लिए, docs.couchbase.com/mcp-server पर जाएँ।

विषय-सूची

• Couchbase MCP सर्वर क्यों
• उदाहरण प्रॉम्प्ट
• विशेषताएँ/टूल
• पूर्वापेक्षाएँ
• कॉन्फ़िगरेशन
• ऑपरेशनल इनसाइट्स सर्वर
• स्ट्रीमेबल HTTP ट्रांसपोर्ट मोड
• SSE ट्रांसपोर्ट मोड
• OAuth 2.1 प्राधिकरण
• Docker इमेज
• उपयोग डेटा संग्रह
• समस्या निवारण युक्तियाँ
• एकीकरण परीक्षण
• FAQ
• योगदान
• समर्थन नीति

Couchbase MCP सर्वर क्यों

• डिफ़ॉल्ट रूप से सुरक्षित — लेखन संचालन (दस्तावेज़ अपसर्ट/इन्सर्ट/डिलीट और डेटा-संशोधित SQL++ क्वेरी) तब तक अवरुद्ध रहते हैं जब तक आप स्पष्ट रूप से CB_MCP_READ_ONLY_MODE=false सेट नहीं करते, और व्यक्तिगत टूल को अक्षम या उपयोगकर्ता पुष्टि के पीछे गेट किया जा सकता है।
• Capella और स्व-प्रबंधित क्लस्टरों के साथ काम करता है — वही कॉन्फ़िगरेशन Couchbase Capella (पूरी तरह से प्रबंधित) या स्व-होस्टेड Couchbase सर्वर क्लस्टर से जुड़ता है।
• RBAC-जागरूक — टूल अक्षमीकरण LLM व्यवहार को निर्देशित करने के लिए एक सुविधा परत है; अंतर्निहित Couchbase उपयोगकर्ता की भूमिका-आधारित पहुँच नियंत्रण प्राधिकृत सुरक्षा सीमा बनी रहती है।
• उत्पादन ट्रांसपोर्ट — स्थानीय डेस्कटॉप क्लाइंट्स के लिए STDIO पर चलाएँ, या साझा/दूरस्थ तैनाती के लिए वैकल्पिक OAuth 2.1 (JWT/JWKS, प्रदाता-अज्ञेय — Auth0, Okta, Keycloak, Entra, Cognito, आदि) के साथ स्ट्रीमेबल HTTP।
• कोई भी MCP क्लाइंट — Claude Desktop, Cursor, Windsurf, VS Code, और JetBrains AI Assistant/Junie के साथ परीक्षण किया गया; MCP विनिर्देश लागू करने वाले किसी भी क्लाइंट के साथ काम करता है।

उदाहरण प्रॉम्प्ट

एक बार सर्वर कनेक्ट हो जाने पर, आप अपने AI सहायक के माध्यम से अपने Couchbase क्लस्टर से प्राकृतिक भाषा में बात कर सकते हैं। उदाहरण के लिए:

• "इस क्लस्टर में मेरे पास कौन से बकेट, स्कोप और कलेक्शन हैं, और orders कलेक्शन की स्कीमा क्या है?"
• "users कलेक्शन में 10 सबसे हाल के दस्तावेज़ खोजने के लिए एक SQL++ क्वेरी चलाएँ where status = 'active'।"
• "पिछले घंटे में इस क्लस्टर पर 5 सबसे धीमी क्वेरी कौन सी हैं, और क्या उनमें से किसी में कवरिंग इंडेक्स गायब है?"
• "जाँचें कि क्या यह क्लस्टर स्वस्थ है और मुझे बताएं कि कौन सी सेवाएँ चल रही हैं।"
• "इन फ़ील्ड्स के साथ products कलेक्शन में एक नया दस्तावेज़ इन्सर्ट करें: ..." (CB_MCP_READ_ONLY_MODE=false की आवश्यकता है)

विशेषताएँ/टूल

यह वितरण दो सर्वर भेजता है: ऑपरेशनल सर्वर (डिफ़ॉल्ट — नीचे दी गई तालिकाएँ) couchbase SDK के माध्यम से एक नियमित Couchbase क्लस्टर से बात करता है, और ऑपरेशनल इनसाइट्स सर्वर (नीचे इसकी अपनी तालिका) couchbase-operational-insights SDK के माध्यम से ऑपरेशनल इनसाइट्स क्लस्टरों से बात करता है।

क्लस्टर सेटअप और स्वास्थ्य टूल

डेटा मॉडल और स्कीमा खोज टूल

दस्तावेज़ KV संचालन टूल

क्वेरी और इंडेक्सिंग टूल

पूर्ण-पाठ खोज (FTS) टूल

Couchbase सर्वर 7.6+ और खोज सेवा की आवश्यकता है। वेक्टर खोज इन टूल द्वारा समर्थित नहीं है (अलग वेक्टर खोज टूलिंग देखें)।

क्वेरी प्रदर्शन विश्लेषण टूल

ऑपरेशनल इनसाइट्स टूल

अलग operational-insights सर्वर द्वारा पंजीकृत (नीचे ऑपरेशनल इनसाइट्स सर्वर देखें), डिफ़ॉल्ट operational सर्वर द्वारा नहीं।

सर्वर एसिंक्रोनस अनुरोध API टूल लंबी चलने वाली क्वेरी के लिए एक प्रारंभ → पोल → त्याग-या-रद्द प्रवाह बनाते हैं: run_query_async एक query_handle लौटाता है, get_async_query_results को तब तक पोल किया जाता है जब तक यह तैयारी की रिपोर्ट नहीं करता (और पंक्तियाँ लौटाता है), फिर या तो discard_async_query_results परिणाम मुक्त करता है या, अभी भी चल रही क्वेरी के लिए, cancel_async_query इसे रोकता है।

नोट: get_collections_in_scope, get_schema_for_collection, create_index और list_indexes दोनों सर्वरों पर मौजूद हैं, भिन्न व्यवहार के साथ। (get_server_configuration_status भी दोनों पर दिखाई देता है, लेकिन यह जानबूझकर एक साझा टूल है — समान कार्यान्वयन, समान परिणाम आकार — इसलिए इसे अलग करने की आवश्यकता नहीं है।) प्रत्येक सर्वर एक अलग प्रक्रिया है, इसलिए यह केवल तभी चिंता का विषय है जब एक एकल MCP क्लाइंट operational और operational-insights दोनों को एक साथ पंजीकृत करता है — उस स्थिति में, क्लाइंट कॉन्फ़िगरेशन परत पर अलग करें (जैसे क्लाइंट के अपने कॉन्फ़िग में दो सर्वर प्रविष्टियों को अलग नाम देकर)।

पूर्वापेक्षाएँ

• Python 3.10 या उच्चतर।
• एक चालू Couchbase क्लस्टर। शुरू करने का सबसे आसान तरीका Capella निःशुल्क स्तर का उपयोग करना है, जो Couchbase सर्वर का पूरी तरह से प्रबंधित संस्करण है। आप निर्देशों का पालन करके नमूना डेटासेट में से एक आयात कर सकते हैं या अपना स्वयं का डेटा आयात कर सकते हैं।
• सर्वर चलाने के लिए uv स्थापित।
• सर्वर को Claude से जोड़ने के लिए Claude Desktop जैसा एक MCP क्लाइंट स्थापित। निर्देश Claude Desktop और Cursor के लिए प्रदान किए गए हैं। अन्य MCP क्लाइंट भी उपयोग किए जा सकते हैं।

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

MCP सर्वर को पूर्व-निर्मित PyPI पैकेज या uv का उपयोग करके स्रोत से चलाया जा सकता है।

PyPI से चलाना

हम MCP सर्वर के लिए एक पूर्व-निर्मित PyPI पैकेज प्रकाशित करते हैं।

MCP क्लाइंट्स के लिए पूर्व-निर्मित पैकेज का उपयोग करके सर्वर कॉन्फ़िगरेशन

बेसिक प्रमाणीकरण

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

या

mTLS

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}

नोट: यदि आपके क्लाइंट में अन्य MCP सर्वर उपयोग में हैं, तो आप इसे मौजूदा mcpServers ऑब्जेक्ट में जोड़ सकते हैं।

स्रोत से चलाना

MCP सर्वर को इस रिपॉजिटरी का उपयोग करके स्रोत से चलाया जा सकता है।

रिपॉजिटरी को अपनी स्थानीय मशीन पर क्लोन करें

git clone https://github.com/couchbase/mcp-server-couchbase.git

MCP क्लाइंट्स के लिए स्रोत का उपयोग करके सर्वर कॉन्फ़िगरेशन

यह Claude Desktop, Cursor, Windsurf Editor जैसे MCP क्लाइंट्स के लिए सामान्य कॉन्फ़िगरेशन है।

{
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/mcp-server-couchbase/",
        "run",
        "src/mcp_server.py"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

नोट: path/to/cloned/repo/mcp-server-couchbase/ आपकी स्थानीय मशीन पर क्लोन किए गए रिपॉजिटरी का पथ होना चाहिए। अंत में ट्रेलिंग स्लैश न भूलें!

नोट: यदि आपके क्लाइंट में अन्य MCP सर्वर उपयोग में हैं, तो आप इसे मौजूदा mcpServers ऑब्जेक्ट में जोड़ सकते हैं।

MCP सर्वर के लिए अतिरिक्त कॉन्फ़िगरेशन

सर्वर को पर्यावरण चर या कमांड लाइन तर्कों का उपयोग करके कॉन्फ़िगर किया जा सकता है:

केवल-पठन मोड कॉन्फ़िगरेशन

CB_MCP_READ_ONLY_MODE लेखन संचालन को नियंत्रित करने वाला एकमात्र स्विच है:

• जब true (डिफ़ॉल्ट): सभी लेखन संचालन (KV, क्वेरी, स्कोप/कलेक्शन प्रबंधन, और इंडेक्स प्रबंधन) अक्षम हैं। सभी लेखन टूल (KV: upsert, insert, replace, delete, sub-document mutate; स्कोप/कलेक्शन प्रबंधन: create_scope, create_collection, delete_scope, delete_collection; इंडेक्स प्रबंधन: create_index, build_index, drop_index) लोड नहीं होते और LLM के लिए उपलब्ध नहीं होंगे, और डेटा या संरचना को संशोधित करने वाली SQL++ क्वेरी अवरुद्ध हैं।
• जब false: सभी लेखन टूल लोड होते हैं और SQL++ डेटा/संरचना संशोधन क्वेरी की अनुमति है।

यह LLM द्वारा अनजाने डेटा संशोधनों को रोकने के लिए अनुशंसित सुरक्षित डिफ़ॉल्ट है।

नोट: प्रमाणीकरण के लिए, आपको या तो उपयोगकर्ता नाम और पासवर्ड या क्लाइंट प्रमाणपत्र और कुंजी पथ की आवश्यकता होती है। वैकल्पिक रूप से, आप CA रूट प्रमाणपत्र पथ निर्दिष्ट कर सकते हैं जिसका उपयोग सर्वर प्रमाणपत्रों को मान्य करने के लिए किया जाएगा। यदि क्लाइंट प्रमाणपत्र और कुंजी पथ और उपयोगकर्ता नाम और पासवर्ड दोनों निर्दिष्ट हैं, तो प्रमाणीकरण के लिए क्लाइंट प्रमाणपत्रों का उपयोग किया जाएगा।

टूल अक्षम करना

आप विशिष्ट टूल्स को अक्षम कर सकते हैं ताकि उन्हें लोड होने और MCP क्लाइंट को उजागर होने से रोका जा सके। अक्षम किए गए टूल्स टूल डिस्कवरी में दिखाई नहीं देंगे और LLM द्वारा उन्हें आमंत्रित नहीं किया जा सकता।

समर्थित प्रारूप

अल्पविराम-पृथक सूची:

# Environment variable
CB_MCP_DISABLED_TOOLS="upsert_document_by_id, delete_document_by_id"

# Command line
uvx couchbase-mcp-server --disabled-tools upsert_document_by_id, delete_document_by_id

फ़ाइल पथ (प्रति पंक्ति एक टूल नाम):

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

# Command line
uvx couchbase-mcp-server --disabled-tools disabled_tools.txt

फ़ाइल प्रारूप (जैसे, disabled_tools.txt):

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

# से शुरू होने वाली पंक्तियाँ टिप्पणियों के रूप में मानी जाती हैं और अनदेखी की जाती हैं।

MCP क्लाइंट कॉन्फ़िगरेशन उदाहरण

अल्पविराम-पृथक सूची का उपयोग करना:

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "upsert_document_by_id,delete_document_by_id"
      }
    }
  }
}

फ़ाइल पथ का उपयोग करना (कई टूल्स के लिए अनुशंसित):

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "/path/to/disabled_tools.txt"
      }
    }
  }
}

महत्वपूर्ण सुरक्षा नोट

चेतावनी: केवल टूल्स को अक्षम करना यह गारंटी नहीं देता कि कुछ ऑपरेशन नहीं किए जा सकते। अंतर्निहित डेटाबेस उपयोगकर्ता की RBAC (रोल-आधारित एक्सेस नियंत्रण) अनुमतियाँ प्राधिकृत सुरक्षा नियंत्रण हैं।

उदाहरण के लिए, भले ही आप upsert_document_by_id और delete_document_by_id को अक्षम कर दें, डेटा संशोधन अभी भी run_sql_plus_plus_query टूल के माध्यम से SQL++ DML स्टेटमेंट्स (INSERT, UPDATE, DELETE, MERGE) का उपयोग करके हो सकते हैं, जब तक कि:

• CB_MCP_READ_ONLY_MODE को true (डिफ़ॉल्ट) पर सेट किया गया है, या
• डेटाबेस उपयोगकर्ता के पास डेटा संशोधन के लिए आवश्यक RBAC अनुमतियाँ नहीं हैं

सर्वोत्तम अभ्यास: हमेशा अपने Couchbase उपयोगकर्ता क्रेडेंशियल्स पर उचित RBAC अनुमतियाँ प्राथमिक सुरक्षा उपाय के रूप में कॉन्फ़िगर करें। टूल अक्षम करने का उपयोग LLM व्यवहार को मार्गदर्शित करने और हमले की सतह को कम करने के लिए एक अतिरिक्त परत के रूप में करें, न कि एकमात्र सुरक्षा नियंत्रण के रूप में।

टूल कॉल्स के लिए उद्बोधन/पुष्टि

आप निष्पादन से पहले विशिष्ट टूल्स के लिए स्पष्ट उपयोगकर्ता पुष्टि की आवश्यकता कर सकते हैं (जब MCP क्लाइंट उद्बोधन का समर्थन करता है)।

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-tools इन प्रारूपों का समर्थन करता है:

• अल्पविराम-पृथक सूची
• फ़ाइल पथ (प्रति पंक्ति एक टूल नाम, # टिप्पणियाँ समर्थित)

उदाहरण:

# Environment variable
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"

# Command line
uvx couchbase-mcp-server --confirmation-required-tools delete_document_by_id,replace_document_by_id

जब एक सूचीबद्ध टूल आमंत्रित किया जाता है:

• यदि क्लाइंट उद्बोधन का समर्थन करता है, तो उपयोगकर्ता को पुष्टि करने के लिए संकेत दिया जाता है।
• यदि क्लाइंट उद्बोधन का समर्थन नहीं करता है, तो टूल पिछड़े संगतता के लिए बिना पुष्टि के निष्पादित होता है।

आप सर्वर का संस्करण भी जांच सकते हैं:

uvx couchbase-mcp-server --version

लॉगिंग

MCP सर्वर डिफ़ॉल्ट रूप से stderr पर लॉग करता है। लॉगिंग अतिरिक्त कॉन्फ़िगरेशन में सूचीबद्ध CB_MCP_LOG_* चरों के साथ कॉन्फ़िगर की जाती है:

• CB_MCP_LOG_LEVEL — कितना लॉग किया जाता है: info (डिफ़ॉल्ट) जीवनचक्र घटनाओं और टूल आमंत्रणों को लॉग करता है, debug विस्तृत आंतरिक विवरण जोड़ता है, और off सभी लॉगिंग अक्षम करता है।
• CB_MCP_LOG_SINKS — लॉग कहाँ जाते हैं: stderr (डिफ़ॉल्ट), प्रति-स्तर घूर्णन फ़ाइलें (file), या दोनों। file के साथ, प्रति स्तर एक फ़ाइल लिखी जाती है (उदाहरण के लिए mcp_server.info.log और mcp_server.error.log) CB_MCP_LOG_FILE द्वारा निर्धारित पथ पर।
• घूर्णन आकार — CB_MCP_LOG_ROTATION_MAX_SIZE_MB वैश्विक आकार है (MB में) जिस पर प्रत्येक प्रति-स्तर फ़ाइल घूमती है। CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB (ERROR/WARNING/INFO/DEBUG) के साथ व्यक्तिगत स्तरों को ओवरराइड करें, MB में भी, जो अनसेट होने पर वैश्विक से विरासत में मिलते हैं। 0 (वैश्विक या प्रति-स्तर) का आकार अमान्य है और स्टार्टअप चेतावनी के साथ डिफ़ॉल्ट (1 MB) पर वापस आ जाता है। CB_MCP_LOG_MAX_BYTES (बाइट्स) अप्रचलित है लेकिन पिछड़े संगतता के लिए अभी भी सम्मानित है; इसे अनदेखा किया जाता है जब CB_MCP_LOG_ROTATION_MAX_SIZE_MB भी सेट होता है, और स्टार्टअप पर एक अप्रचलन चेतावनी प्रिंट करता है।
• प्रतिधारण — CB_MCP_LOG_RETENTION_BACKUP_COUNT सेट करता है कि प्रति स्तर कितने घूर्णित बैकअप रखे जाते हैं (लाइव फ़ाइल को छोड़कर); 1 का डिफ़ॉल्ट पिछले व्यवहार को संरक्षित करता है। CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT (ERROR/WARNING/INFO/DEBUG) के साथ व्यक्तिगत स्तरों को ओवरराइड करें, जो अनसेट होने पर वैश्विक मान से विरासत में मिलते हैं। उस स्तर के लिए केवल लाइव फ़ाइल रखने के लिए एक गिनती को 0 पर सेट करें — यह अभी भी घूर्णन आकार द्वारा सीमित है (बैकअप के बजाय रोलओवर पर रीसेट)।
• सर्वर-कॉन्फ़िग स्नैपशॉट — जब file सिंक सक्रिय होता है, तो एक एक-शॉट रिकॉर्ड (OS, Python, निर्भरता संस्करण, परिवहन, हल किया गया लॉगिंग कॉन्फ़िग, और संपादित सर्वर कॉन्फ़िग) एक समर्पित mcp_server_config.log.json फ़ाइल में JSON के रूप में लिखा जाता है (CB_MCP_LOG_FILE आधार से व्युत्पन्न)। यह प्रत्येक प्रारंभ पर अधिलेखित होता है, इसलिए समर्थन के पास हमेशा वर्तमान कॉन्फ़िग होता है और यह कभी भी घूर्णन लॉग से बाहर नहीं जाता।

# Enable debug logging to both stderr and rotating per-level files
uvx couchbase-mcp-server --log-level=debug --log-sinks=stderr,file

# Keep 30 rotated ERROR backups but only the live DEBUG file
uvx couchbase-mcp-server --log-level=debug --log-sinks=file \
  --log-error-retention-backup-count=30 --log-debug-retention-backup-count=0

अधिक विवरण के लिए, दस्तावेज़ीकरण देखें।

क्लाइंट विशिष्ट कॉन्फ़िगरेशन

Operational Insights सर्वर

डिफ़ॉल्ट operational सर्वर (वह जो ऊपर हर अनुभाग वर्णन करता है) के साथ, यह वितरण Operational Insights क्लस्टरों के लिए एक दूसरा सर्वर भेजता है, जो अलग couchbase-operational-insights SDK का उपयोग करता है। यह एक नियमित Couchbase क्लस्टर से एक अलग उत्पाद है और अपने स्वयं के पोर्ट पर एक स्वतंत्र प्रक्रिया के रूप में चलता है।

इसे CLI उपकमांड के रूप में operational-insights पास करके चलाएं (या इसे कंटेनर के कमांड के रूप में जोड़ें):

uvx couchbase-mcp-server operational-insights
# or, from source:
uv run src/mcp_server.py operational-insights
# or, via Docker:
docker run --rm -i \
  -e CB_OI_CONNECTION_STRING=http://localhost:8095 \
  -e CB_OI_USERNAME=Administrator \
  -e CB_OI_PASSWORD=password \
  couchbase/mcp-server:<version> operational-insights

--connection-string एक HTTP(S) URL है, couchbase:// कनेक्शन स्ट्रिंग नहीं — जैसे स्थानीय Operational Insights सर्वर के लिए http://localhost:8095, या Capella के लिए https://<host>:18095। यह सबसे सामान्य गलत कॉन्फ़िगरेशन है जब इस सर्वर को किसी क्लस्टर की ओर इंगित किया जाता है।

हर अन्य फ़्लैग (--read-only-mode, --transport, --host, --port, --disabled-tools, --confirmation-required-tools, --log-*, --oauth-*) operational सर्वर के समान है — देखें Additional Configuration for MCP Server — पोर्ट (8001, 8000 नहीं) और लॉग फ़ाइल के डिफ़ॉल्ट को छोड़कर (mcp_server_operational_insights.log, mcp_server.log नहीं), क्योंकि दो सर्वर इनमें से कोई भी साझा नहीं कर सकते। OAuth समान स्कोप लेबल का उपयोग करता है (couchbase-mcp:read / couchbase-mcp:write) operational सर्वर की तरह, इसलिए एक मौजूदा IdP कॉन्फ़िगरेशन बिना बदलाव के दोनों के लिए काम करता है।

उदाहरण MCP क्लाइंट कॉन्फ़िगरेशन:

{
  "mcpServers": {
    "couchbase-operational-insights": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OI_CONNECTION_STRING": "http://localhost:8095",
        "CB_OI_USERNAME": "Administrator",
        "CB_OI_PASSWORD": "password"
      }
    }
  }
}

टूल सूची के लिए ऊपर Operational Insights tools देखें, और operational सर्वर के साथ साझा किए गए तीन टूल नामों के बारे में वहाँ दिया गया नोट देखें।

दोनों सर्वर एक ही MCP Registry सूची साझा करते हैं, io.github.couchbase/mcp-server-couchbase, से प्रकाशित server.json। सूची में प्रत्येक सर्वर के लिए एक अलग पैकेज प्रविष्टि है (PyPI और Docker)। प्रत्येक प्रविष्टि अपना सबकमांड (operational या operational-insights) पास करती है और केवल उस सर्वर के तर्क और पर्यावरण चर घोषित करती है।

Streamable HTTP Transport Mode

MCP सर्वर को Streamable HTTP ट्रांसपोर्ट मोड में चलाया जा सकता है जो कई क्लाइंट को HTTP के माध्यम से एक ही सर्वर इंस्टेंस से कनेक्ट करने की अनुमति देता है। इस मोड में MCP सर्वर से कनेक्ट करने का प्रयास करने से पहले जाँचें कि आपका MCP क्लाइंट स्ट्रीमेबल HTTP ट्रांसपोर्ट का समर्थन करता है या नहीं।

नोट: OAuth 2.1 प्राधिकरण इस ट्रांसपोर्ट पर समर्थित है। देखें OAuth 2.1 Authorization। OAuth कॉन्फ़िगर किए बिना, HTTP एंडपॉइंट अप्रमाणित है।

उपयोग

डिफ़ॉल्ट रूप से, MCP सर्वर पोर्ट 8000 पर चलेगा लेकिन इसे --port या CB_MCP_PORT पर्यावरण चर का उपयोग करके कॉन्फ़िगर किया जा सकता है।

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=http

सर्वर http://localhost:8000/mcp पर उपलब्ध होगा। इसका उपयोग स्ट्रीमेबल HTTP ट्रांसपोर्ट मोड का समर्थन करने वाले MCP क्लाइंट जैसे Cursor में किया जा सकता है।

MCP क्लाइंट कॉन्फ़िगरेशन

{
  "mcpServers": {
    "couchbase-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

SSE Transport Mode

MCP सर्वर को Server-Sent Events (SSE) ट्रांसपोर्ट मोड में चलाने का विकल्प है।

नोट: SSE मोड को MCP द्वारा अप्रचलित कर दिया गया है। हमारे पास Streamable HTTP के लिए समर्थन है।

SSE: उपयोग

डिफ़ॉल्ट रूप से, MCP सर्वर पोर्ट 8000 पर चलेगा लेकिन इसे --port या CB_MCP_PORT पर्यावरण चर का उपयोग करके कॉन्फ़िगर किया जा सकता है।

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=sse

सर्वर http://localhost:8000/sse पर उपलब्ध होगा। इसका उपयोग SSE ट्रांसपोर्ट मोड का समर्थन करने वाले MCP क्लाइंट जैसे Cursor में किया जा सकता है।

SSE: MCP क्लाइंट कॉन्फ़िगरेशन

{
  "mcpServers": {
    "couchbase-sse": {
      "url": "http://localhost:8000/sse"
    }
  }
}

OAuth 2.1 प्राधिकरण

--transport=http के साथ चलने पर, MCP सर्वर एक OAuth 2.1 संसाधन सर्वर के रूप में कार्य कर सकता है: यह आपके पहचान प्रदाता के JWKS के विरुद्ध आने वाले बियरर JWT को मान्य करता है। यह प्रदाता-अज्ञेयवादी है (कोई भी OAuth 2.1 / OIDC प्रदाता जो JWKS प्रकाशित करता है — Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra, आदि) और टोकन जारी नहीं करता या उपयोगकर्ताओं का प्रबंधन नहीं करता। OAuth सेटिंग्स stdio पर अनदेखी की जाती हैं।

OAuth को Additional Configuration में सूचीबद्ध CB_MCP_OAUTH_* चर के साथ कॉन्फ़िगर किया गया है:

• OAuth केवल तब सक्रिय होता है जब CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER, और CB_MCP_OAUTH_JWT_AUDIENCE तीनों सेट हों; उनमें से केवल कुछ सेट करने पर स्टार्टअप पर विफलता होती है।
• CB_MCP_OAUTH_MCP_BASE_URL सेट करने से अतिरिक्त रूप से RFC 9728 Protected Resource Metadata प्रकाशित होता है ताकि PRM-जागरूक क्लाइंट प्राधिकरण सर्वर की खोज कर सकें।
• एक्सेस टोकन के scope/scp दावे से पढ़े गए दो स्कोपों द्वारा नियंत्रित है: couchbase-mcp:read (रीड टूल, SQL++ सहित) और couchbase-mcp:write (राइट टूल: KV म्यूटेशन, स्कोप/कलेक्शन प्रबंधन, और इंडेक्स प्रबंधन)। पूर्ण एक्सेस के लिए दोनों की आवश्यकता है। यदि आपका IdP उन विहित लेबलों को उत्सर्जित नहीं कर सकता है, तो उन्हें CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL के साथ ओवरराइड करें।

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --transport=http \
  --oauth-jwks-uri='https://auth.example.com/.well-known/jwks.json' \
  --oauth-issuer='https://auth.example.com/' \
  --oauth-audience='couchbase-mcp-server' \
  --oauth-mcp-base-url='<public_base_url_of_this_server>'

पूर्ण विवरण के लिए, दस्तावेज़ीकरण देखें।

Docker छवि

MCP सर्वर को Docker कंटेनर के रूप में भी बनाया और चलाया जा सकता है। पूर्व-निर्मित छवियाँ DockerHub पर पाई जा सकती हैं या docker pull docker.io/couchbase/mcp-server:latest के माध्यम से खींची जा सकती हैं।

वैकल्पिक रूप से, हम Docker MCP Catalog का हिस्सा हैं।

छवि बनाना

docker build -t mcp/couchbase-src .

docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
  -t mcp/couchbase-src .

# Build with default image name (mcp/couchbase-src)
./build.sh

# Build with custom image name
./build.sh my-custom/image-name

# View git commit hash in image
docker inspect --format='{{index .Config.Labels "org.opencontainers.image.revision"}}' mcp/couchbase-src:latest

# View all metadata labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latest

चलाना

MCP सर्वर को पर्यावरण चर के साथ चलाया जा सकता है जिनका उपयोग Couchbase सेटिंग्स को कॉन्फ़िगर करने के लिए किया जाता है। पर्यावरण चर Additional Configuration section में वर्णित समान हैं।

स्वतंत्र Docker कंटेनर

docker run --rm -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_MCP_TRANSPORT='<http|sse|stdio>' \
  -e CB_MCP_READ_ONLY_MODE='<true|false>' \
  -e CB_MCP_CONFIRMATION_REQUIRED_TOOLS='delete_document_by_id' \
  -e CB_MCP_PORT=9001 \
  -e CB_MCP_HOST=0.0.0.0 \
  -p 9001:9001 \
  mcp/couchbase-src

CB_MCP_PORT और CB_MCP_HOST पर्यावरण चर केवल HTTP ट्रांसपोर्ट मोड जैसे http और sse के मामले में लागू होते हैं।

Docker: MCP क्लाइंट कॉन्फ़िगरेशन

Docker छवि का उपयोग निम्नलिखित कॉन्फ़िगरेशन के साथ stdio ट्रांसपोर्ट मोड में किया जा सकता है।

{
  "mcpServers": {
    "couchbase-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CB_CONNECTION_STRING=<couchbase_connection_string>",
        "-e",
        "CB_USERNAME=<database_user>",
        "-e",
        "CB_PASSWORD=<database_password>",
        "mcp/couchbase-src"
      ]
    }
  }
}

नोट्स

• couchbase_connection_string मान इस बात पर निर्भर करता है कि Couchbase सर्वर एक ही होस्ट मशीन पर, किसी अन्य Docker कंटेनर में, या दूरस्थ होस्ट पर चल रहा है या नहीं। यदि आपका Couchbase सर्वर आपकी होस्ट मशीन पर चल रहा है, तो आपका कनेक्शन स्ट्रिंग संभवतः couchbase://host.docker.internal के रूप में होगा। विवरण के लिए docker दस्तावेज़ीकरण देखें।
• आप --network=<your_network> विकल्प का उपयोग करके कंटेनर की नेटवर्किंग निर्दिष्ट कर सकते हैं। आपके द्वारा चुना गया नेटवर्क आपके वातावरण पर निर्भर करता है; डिफ़ॉल्ट bridge है। विवरण के लिए, docker में नेटवर्क ड्राइवर देखें।

LLM से जुड़े जोखिम

• बड़े भाषा मॉडल और समान तकनीक का उपयोग जोखिमों से जुड़ा है, जिसमें गलत या हानिकारक आउटपुट की संभावना शामिल है।
• Couchbase ऐसे आउटपुट की गुणवत्ता या सटीकता की समीक्षा या मूल्यांकन नहीं करता है, और ऐसे आउटपुट Couchbase के विचारों को प्रतिबिंबित नहीं कर सकते हैं।
• बड़े भाषा मॉडल और संबंधित तकनीक का उपयोग करने का निर्णय लेना, और किसी भी लाइसेंस शर्तों, उपयोग की शर्तों, और आपके संगठन की नीतियों का पालन करना पूरी तरह से आपकी जिम्मेदारी है।

उपयोग डेटा संग्रह

यह उत्पाद स्वचालित रूप से उपयोग और प्रदर्शन डेटा (जैसे उत्पाद नाम और संस्करण) और ब्राउज़र जानकारी (जैसे IP पता) एकत्र करता है (सामूहिक रूप से, "उपयोग डेटा")। Couchbase उपयोग डेटा का उपयोग, अन्य डेटा के साथ जो आप Couchbase को प्रदान कर सकते हैं (जैसे आपका उपयोगकर्ता नाम या ईमेल पता), हमारे उत्पादों को विकसित और बेहतर बनाने के साथ-साथ हमारे बिक्री और विपणन कार्यक्रमों को सूचित करने के लिए करता है। हम Couchbase उत्पादों में संग्रहीत किसी भी डेटा तक पहुँच या संग्रह नहीं करते हैं। हम उपयोग डेटा का उपयोग समग्र उपयोग पैटर्न को समझने और हमारे उत्पादों को आपके लिए अधिक उपयोगी बनाने के लिए करते हैं। Couchbase कैसे जानकारी एकत्र, सुरक्षा और संसाधित करता है, इसके बारे में अधिक जानकारी के लिए, कृपया https://www.couchbase.com/privacy-policy. पर देखे जाने वाली Couchbase गोपनीयता नीति देखें।

समस्या निवारण युक्तियाँ

• यदि स्रोत से चला रहे हैं तो सुनिश्चित करें कि आपके MCP सर्वर रिपॉजिटरी का पथ कॉन्फ़िगरेशन में सही है।
• सत्यापित करें कि आपका Couchbase कनेक्शन स्ट्रिंग, डेटाबेस उपयोगकर्ता नाम, पासवर्ड या प्रमाणपत्रों का पथ सही है।
• यदि Couchbase Capella का उपयोग कर रहे हैं, तो सुनिश्चित करें कि क्लस्टर उस मशीन से पहुंच योग्य है जहाँ MCP सर्वर चल रहा है।
• जाँचें कि डेटाबेस उपयोगकर्ता के पास कम से कम एक बकेट तक पहुँचने के लिए उचित अनुमतियाँ हैं।
• पुष्टि करें कि uv पैकेज मैनेजर ठीक से स्थापित और पहुंच योग्य है। आपको कॉन्फ़िगरेशन में command फ़ील्ड में uv/uvx का पूर्ण पथ प्रदान करने की आवश्यकता हो सकती है।
• MCP सर्वर के साथ समस्याओं का संकेत देने वाली किसी भी त्रुटि या चेतावनी के लिए लॉग जाँचें। लॉग का स्थान आपके MCP क्लाइंट पर निर्भर करता है।
• यदि आप अपने स्थानीय MCP सर्वर रिपॉजिटरी को अपडेट करने के बाद स्रोत से अपने MCP सर्वर को चलाने में समस्याएँ देख रहे हैं, तो निर्भरताओं को अपडेट करने के लिए uv sync चलाने का प्रयास करें।

एकीकरण परीक्षण

हम उच्च-स्तरीय MCP एकीकरण परीक्षण प्रदान करते हैं ताकि यह सत्यापित किया जा सके कि सर्वर अपेक्षित टूल प्रदर्शित करता है और उन्हें डेमो Couchbase क्लस्टर के विरुद्ध लागू किया जा सकता है।

1. डेमो क्लस्टर क्रेडेंशियल निर्यात करें:
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • वैकल्पिक: CB_MCP_TEST_BUCKET (परीक्षणों के दौरान जाँचने के लिए एक बकेट)
   • वैकल्पिक, Operational Insights सर्वर के अपने परीक्षणों के लिए: CB_OI_CONNECTION_STRING / CB_OI_USERNAME / CB_OI_PASSWORD। वे परीक्षण अनसेट होने पर स्वचालित रूप से छोड़ दिए जाते हैं (विफल नहीं होते)।
2. परीक्षण चलाएँ:

uv run --extra dev pytest tests/integration -v

FAQ

Couchbase MCP सर्वर क्या है? यह Model Context Protocol का एक स्व-होस्टेड कार्यान्वयन है जो AI सहायकों और एजेंटों (Claude, Cursor, Windsurf, VS Code Copilot, JetBrains AI Assistant/Junie, और किसी भी अन्य MCP क्लाइंट) को प्राकृतिक भाषा का उपयोग करके Couchbase क्लस्टर में डेटा क्वेरी करने और, वैकल्पिक रूप से, संशोधित करने की अनुमति देता है।

मैं Claude Desktop को Couchbase से कैसे कनेक्ट करूँ? सर्वर को uvx couchbase-mcp-server के साथ स्थापित करें (या इसे स्रोत या Docker से चलाएँ), फिर Configuration में दिखाए अनुसार Claude Desktop के claude_desktop_config.json में इसका कॉन्फ़िगरेशन जोड़ें। Claude Desktop को पुनः आरंभ करें और यह नए टूल उठा लेगा।

क्या मैं इसे Couchbase Capella के साथ उपयोग कर सकता हूँ? हाँ। वही CB_CONNECTION_STRING/CB_USERNAME/CB_PASSWORD (या mTLS प्रमाणपत्र) कॉन्फ़िगरेशन Couchbase Capella और स्व-प्रबंधित Couchbase सर्वर क्लस्टर दोनों के लिए काम करता है।

क्या AI एजेंट को मेरे डेटाबेस में लिखने देना सुरक्षित है? डिफ़ॉल्ट रूप से, CB_MCP_READ_ONLY_MODE सत्य है, इसलिए सभी लेखन ऑपरेशन — दस्तावेज़ अपसेर्ट/इन्सर्ट/रिप्लेस/डिलीट और डेटा-संशोधित SQL++ कथन — अक्षम हैं और लेखन टूल लोड भी नहीं होते। आप व्यक्तिगत टूल को भी अक्षम कर सकते हैं (देखें Disabling Tools) या विशिष्ट टूल चलाने से पहले स्पष्ट उपयोगकर्ता पुष्टि की आवश्यकता हो सकती है (देखें Elicitation/Confirmation)। टूल-स्तरीय नियंत्रण LLM व्यवहार का मार्गदर्शन करते हैं; आपके Couchbase उपयोगकर्ता की RBAC अनुमतियाँ वास्तविक सुरक्षा सीमा बनी रहती हैं।

क्या मैं स्वयं SQL++ लिखे बिना अपने डेटा के विरुद्ध प्राकृतिक-भाषा क्वेरी चला सकता हूँ? हाँ — अपने AI सहायक से सरल अंग्रेजी में एक प्रश्न पूछें (जैसे "मुझे $100 से अधिक के 10 सबसे हाल के ऑर्डर दिखाएँ") और यह run_sql_plus_plus_query टूल का उपयोग करके उसे SQL++ क्वेरी में अनुवाद कर सकता है। आप सहायक से किसी क्वेरी को explain_sql_plus_plus_query करने या इंडेक्स सलाहकार से सिफारिशें पूछने के लिए भी कह सकते हैं। STDIO, Streamable HTTP और SSE ट्रांसपोर्ट में क्या अंतर है? STDIO एकल स्थानीय MCP क्लाइंट (जैसे Claude Desktop) के लिए है जो सर्वर को सबप्रोसेस के रूप में लॉन्च करता है। Streamable HTTP कई क्लाइंट्स को HTTP पर एक चल रहे सर्वर इंस्टेंस को साझा करने की अनुमति देता है, और OAuth 2.1 का समर्थन करता है। SSE पुराना HTTP ट्रांसपोर्ट है, जिसे अब MCP स्पेक द्वारा Streamable HTTP के पक्ष में हटा दिया गया है — देखें Streamable HTTP Transport Mode।

क्या यह आधिकारिक रूप से Couchbase द्वारा समर्थित है? यह प्रोजेक्ट Couchbase समुदाय-अनुरक्षित है — देखें Support Policy। एंटरप्राइज़ समर्थन Couchbase AI Data Plane के माध्यम से अलग से उपलब्ध है।

योगदान

हम समुदाय से योगदान का स्वागत करते हैं! चाहे आप बग ठीक करना चाहें, सुविधाएँ जोड़ना चाहें, या दस्तावेज़ीकरण में सुधार करना चाहें, आपकी मदद की सराहना की जाती है।

यदि आपको सहायता चाहिए, कोई बग मिला है, या सुधार में योगदान देना चाहते हैं, तो ऐसा करने का सबसे अच्छा स्थान यहीं है — GitHub issue खोलकर।

डेवलपर्स के लिए

यदि आप कोड में योगदान देने या विकास वातावरण स्थापित करने में रुचि रखते हैं:

📖 व्यापक डेवलपर सेटअप निर्देशों के लिए CONTRIBUTING.md देखें, जिसमें शामिल हैं:

• uv के साथ विकास वातावरण सेटअप
• Ruff के साथ कोड लिंटिंग और फ़ॉर्मेटिंग
• प्री-कमिट हुक स्थापना
• प्रोजेक्ट संरचना अवलोकन
• विकास कार्यप्रवाह और अभ्यास

योगदानकर्ताओं के लिए त्वरित प्रारंभ

# Clone and setup
git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

# Run linting
./scripts/lint.sh

📢 समर्थन नीति

इस प्रोजेक्ट में आपकी रुचि की हम वास्तव में सराहना करते हैं! यह प्रोजेक्ट Couchbase समुदाय-अनुरक्षित है, जिसका अर्थ है कि यह हमारी समर्थन टीम द्वारा आधिकारिक रूप से समर्थित नहीं है। हालाँकि, हमारे इंजीनियर इस रेपो की सक्रिय रूप से निगरानी और रखरखाव कर रहे हैं और सर्वोत्तम प्रयास के आधार पर मुद्दों को हल करने का प्रयास करेंगे।

हमारा समर्थन पोर्टल इस प्रोजेक्ट से संबंधित अनुरोधों में सहायता करने में असमर्थ है, इसलिए हम विनम्रतापूर्वक अनुरोध करते हैं कि सभी पूछताछ GitHub के भीतर ही रहें।

आपका सहयोग हम सभी को एक साथ आगे बढ़ने में मदद करता है — धन्यवाद!