Aniket310101 MCP Server Couchbase

🗄️ Couchbase MCP Server for LLMs

A Model Context Protocol (MCP) server that enables LLMs to directly interact with a Couchbase database on a Capella cluster. Query buckets, perform CRUD operations, run N1QL queries, and manage data entirely through natural language.

🚀 Quick Start

Prerequisites

• Node.js version 16 or higher
• A running Couchbase instance (Capella-based)
• Claude Desktop application

Installation

There are two ways to install the Couchbase MCP Server:

Option 1: Using NPX (Recommended)

The quickest way is to install via NPX:

npx -y @couchbasedatabase/couchbase-mcp

Option 2: Manual Installation

If you prefer to clone and run the project:

# Clone the repository
git clone https://github.com/Aniket310101/MCP-Server-Couchbase.git
cd MCP-Server-Couchbase

# Install dependencies
npm install

# Build the project
npm run build

Claude Desktop Integration

Add the following configuration to your Claude Desktop configuration file:

• Windows: %APPDATA%/Claude/claude_desktop_config.json
• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Option 1: Using Package Installation

{
  "mcpServers": {
    "couchbase": {
      "command": "npx",
      "args": ["-y", "@couchbasedatabase/couchbase-mcp"],
      "env": {
        "COUCHBASE_URL": "<COUCHBASE connection string>",
        "COUCHBASE_BUCKET": "<Bucket name>",
        "COUCHBASE_USERNAME": "<Couchbase username>",
        "COUCHBASE_PASSWORD": "<Couchbase password>"
      }
    }
  }
}

Option 2: Using Manual Installation

{
  "mcpServers": {
    "couchbase": {
      "command": "node",
      "args": ["path/to/MCP-Server-Couchbase/dist/index.js"],
      "env": {
        "COUCHBASE_URL": "<COUCHBASE connection string>",
        "COUCHBASE_BUCKET": "<Bucket name>",
        "COUCHBASE_USERNAME": "<Couchbase username>",
        "COUCHBASE_PASSWORD": "<Couchbase password>"
      }
    }
  }
}

Verify the Connection

• Restart the Claude Desktop.
• Now, the Couchbase MCP Server tool should be available in your conversations.

📝 Available Tools

Basic Operations

• query: Execute an N1QL query.
• listBuckets: List all available buckets.

Scope Management

• createScope: Create a new scope in a bucket.
• deleteScope: Delete an existing scope.
• listScopes: List all scopes.

Collection and Document Operations

• createCollection: Create a new collection in a scope.
• deleteCollection: Delete a collection.
• getDocument: Retrieve a document.
• .getDocumentByQuery: Retrieve a document by query.
• upsertDocument: Insert or update a document.
• replaceDocument: Replace a document.
• removeDocument: Delete a document.

Query and Search

• queryDocuments: Query documents via SQL.
• searchCollection: Search for documents in a collection.
• getSearchIndexingStatus: Get the indexing status.
• getIndexFields: Get the index fields.
• getFilterDefinitions: Get the filter definitions.
• getSortSpecifications: Get the sorting specifications.

🛡️ Security Considerations

• Store sensitive information using environment variables, for example:

export COUCHBASE_URL=your_cluster_url
export COUCHBASE_USERNAME=your_username
export COUCHBASE_PASSWORD=your_password

• Use a reverse proxy (such as Nginx) to protect your Couchbase cluster in a production environment.

💻 Usage Examples

Creating Scopes and Collections

# Create a scope
createScope(bucket_name, scope_name)

# Create a collection
createCollection(bucket_name, scope_name, collection_name)

Document Operations

# Insert a document
upsertDocument(bucket_name, scope_name, collection_name, document_id, document_body)

# Retrieve a document
getDocument(bucket_name, scope_name, collection_name, document_id)

# Delete a document
removeDocument(bucket_name, scope_name, collection_name, document_id)

Query and Search

# Execute an N1QL query
queryDocuments(bucket_name, query_string)

# Search a collection
searchCollection(bucket_name, scope_name, collection_name, search_query)

🤝 Contribution

We welcome contributions from the community! Please visit our open - source project in the GitHub repository and submit a pull request.