Couchbase

Couchbase MCP Server

An MCP server implementation of Couchbase that allows LLMs to directly interact with Couchbase clusters.

Features

• Get a list of all the buckets in the cluster
• Get a list of all the scopes and collections in the specified bucket
• Get a list of all the scopes in the specified bucket
• Get a list of all the collections in a specified scope and bucket. Note that this tool requires the cluster to have Query service.
• Get the structure for a collection
• Get a document by ID from a specified scope and collection
• Upsert a document by ID to a specified scope and collection
• Delete a document by ID from a specified scope and collection
• Run a SQL++ query on a specified scope
  • Queries are automatically scoped to the specified bucket and scope, so use collection names directly (e.g., use SELECT * FROM users instead of SELECT * FROM bucket.scope.users)
  • There is an option in the MCP server, CB_MCP_READ_ONLY_QUERY_MODE that is set to true by default to disable running SQL++ queries that change the data or the underlying collection structure. Note that the documents can still be updated by ID.
• Get the status of the MCP server
• Check the cluster credentials by connecting to the cluster
• List all indexes in the cluster with their definitions, with optional filtering by bucket, scope, collection and index name.
• Get index recommendations from Couchbase Index Advisor for a given SQL++ query to optimize query performance
• Get cluster health status and list of all running services
• Query performance analysis tools:
  • Get longest running queries by average service time
  • Get most frequently executed queries
  • Get queries with the largest response sizes
  • Get queries with the largest result counts
  • Get queries that use a primary index (potential performance concern)
  • Get queries that don't use a covering index
  • Get queries that are not selective (index scans return many more documents than final result)

Prerequisites

• Python 3.10 or higher.
• A running Couchbase cluster. The easiest way to get started is to use Capella free tier, which is fully managed version of Couchbase server. You can follow instructions to import one of the sample datasets or import your own.
• uv installed to run the server.
• An MCP client such as Claude Desktop installed to connect the server to Claude. The instructions are provided for Claude Desktop and Cursor. Other MCP clients could be used as well.

Configuration

The MCP server can be run either from the prebuilt PyPI package or the source using uv.

Running from PyPI

We publish a pre built PyPI package for the MCP server.

Server Configuration using Pre built Package for MCP Clients

Basic Authentication

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

or

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

Note: If you have other MCP servers in use in the client, you can add it to the existing mcpServers object.

Running from Source

The MCP server can be run from the source using this repository.

Clone the repository to your local machine.

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

Server Configuration using Source for MCP Clients

This is the common configuration for the MCP clients such as Claude Desktop, Cursor, Windsurf Editor.

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

Note: path/to/cloned/repo/mcp-server-couchbase/ should be the path to the cloned repository on your local machine. Don't forget the trailing slash at the end!

Note: If you have other MCP servers in use in the client, you can add it to the existing mcpServers object.

Additional Configuration for MCP Server

The server can be configured using environment variables or command line arguments:

Environment Variable	CLI Argument	Description	Default
CB_CONNECTION_STRING	--connection-string	Connection string to the Couchbase cluster	Required
CB_USERNAME	--username	Username with access to required buckets for basic authentication	Required (or Client Certificate and Key needed for mTLS)
CB_PASSWORD	--password	Password for basic authentication	Required (or Client Certificate and Key needed for mTLS)
CB_CLIENT_CERT_PATH	--client-cert-path	Path to the client certificate file for mTLS authentication	Required if using mTLS (or Username and Password required)
CB_CLIENT_KEY_PATH	--client-key-path	Path to the client key file for mTLS authentication	Required if using mTLS (or Username and Password required)
CB_CA_CERT_PATH	--ca-cert-path	Path to server root certificate for TLS if server is configured with a self-signed/untrusted certificate. This will not be required if you are connecting to Capella
CB_MCP_READ_ONLY_QUERY_MODE	--read-only-query-mode	Prevent data modification queries	true
CB_MCP_TRANSPORT	--transport	Transport mode: stdio, http, sse	stdio
CB_MCP_HOST	--host	Host for HTTP/SSE transport modes	127.0.0.1
CB_MCP_PORT	--port	Port for HTTP/SSE transport modes	8000

Note: For authentication, you need either the Username and Password or the Client Certificate and key paths. Optionally, you can specify the CA root certificate path that will be used to validate the server certificates. If both the Client Certificate & key path and the username and password are specified, the client certificates will be used for authentication.

You can also check the version of the server using:

uvx couchbase-mcp-server --version

Client Specific Configuration

Claude Desktop

Follow the steps below to use Couchbase MCP server with Claude Desktop MCP client

1. The MCP server can now be added to Claude Desktop by editing the configuration file. More detailed instructions can be found on the MCP quickstart guide.

   • On Mac, the configuration file is located at ~/Library/Application Support/Claude/claude_desktop_config.json
   • On Windows, the configuration file is located at %APPDATA%\Claude\claude_desktop_config.json

   Open the configuration file and add the configuration to the mcpServers section.

2. Restart Claude Desktop to apply the changes.

3. You can now use the server in Claude Desktop to run queries on the Couchbase cluster using natural language and perform CRUD operations on documents.

Logs

The logs for Claude Desktop can be found in the following locations:

• MacOS: ~/Library/Logs/Claude
• Windows: %APPDATA%\Claude\Logs

The logs can be used to diagnose connection issues or other problems with your MCP server configuration. For more details, refer to the official documentation.

Cursor

Follow steps below to use Couchbase MCP server with Cursor:

1. Install Cursor on your machine.

2. In Cursor, go to Cursor > Cursor Settings > Tools & Integrations > MCP Tools. Also, checkout the docs on setting up MCP server configuration from Cursor.

3. Specify the same configuration. You may need to add the server configuration under a parent key of mcpServers.

4. Save the configuration.

5. You will see couchbase as an added server in MCP servers list. Refresh to see i

...(truncated)