playbooks

home / mcp / couchbase mcp server

Couchbase MCP Server

A Model Context Protocol (MCP) server that enables LLMs to interact directly with Couchbase databases. Query buckets, execute N1QL queries, and manage data seamlessly through natural language.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "aniket310101-mcp-server-couchbase": {
      "command": "npx",
      "args": [
        "-y",
        "@couchbasedatabase/couchbase-mcp"
      ],
      "env": {
        "COUCHBASE_URL": "<COUCHBASE CONNECTION STRING>",
        "COUCHBASE_BUCKET": "<BUCKET NAME>",
        "COUCHBASE_PASSWORD": "<COUCHBASE PASSWORD>",
        "COUCHBASE_USERNAME": "<COUCHBASE USERNAME>"
      }
    }
  }
}

You can connect Claude to Couchbase and interact with your Capella data directly through the MCP server. This enables you to query buckets, manage scopes and collections, perform CRUD operations, and run N1QL queries using natural language, all from your conversations.

How to use

You will use an MCP client (like Claude) to communicate with the Couchbase MCP Server. Start the MCP server locally or point your client to a running MCP instance, then issue natural language requests to perform data operations. The server exposes tools for querying data, managing buckets, scopes, collections, and documents, as well as creating indexes. Use simple, clear prompts such as asking to list buckets, create a scope, or retrieve a document by ID. Your client will translate your request into MCP calls and return results in natural language.

To configure your client, provide the MCP server connection details and credentials as environment variables. This ensures sensitive information stays secure and can be rotated easily.

How to install

Prerequisites you need before installing the Couchbase MCP Server:

- Node.js 16 or higher

- A running Couchbase instance on Capella

- Claude Desktop application

Choose one of the installation options below to run the MCP Server locally.

Option 1: Using NPX (Recommended)

npx -y @couchbasedatabase/couchbase-mcp

Option 2: Manual Installation

If you prefer to clone and run the project manually, follow these steps:

# 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 this configuration to your Claude Desktop config file.

Windows: %APPDATA%/Claude/claude_desktop_config.json

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

### Option 1: With 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: With 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>"
      }
    }
  }
}

Available tools

query

Execute N1QL queries against the connected Couchbase bucket, returning results to the user.

listBuckets

List all Buckets available in the connected Couchbase cluster.

createScope

Create a new scope within a specified bucket.

deleteScope

Delete an existing scope from a bucket.

listScopes

List all scopes within a bucket.

createCollection

Create a new collection within a scope.

dropCollection

Delete a collection from a scope.

createDocument

Create a new document in a collection.

getDocument

Retrieve a document by its ID.

updateDocument

Update an existing document by ID.

deleteDocument

Delete a document by ID.

bulkCreateDocuments

Create multiple documents in a single operation.

createIndex

Create a new index on specified fields.

createPrimaryIndex

Create a primary index on a collection.

listIndexes

List all indexes in a bucket.

dropIndex

Drop an existing index.