Mcp Server Couchbase

Couchbase MCP Server

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

[](https://mcp-server.couchbase.com/) [](https://opensource.org/licenses/Apache-2.0) [](https://www.python.org/downloads/) [](https://pypi.org/project/couchbase-mcp-server/) [][cursor-install-basic] [](https://mseep.ai/app/13fce476-0e74-4b1e-ab82-1df2a3204809) [](https://archestra.ai/mcp-catalog/couchbase-ecosystem__mcp-server-couchbase)

For full documentation, visit mcp-server.couchbase.com.

Features/Tools

Cluster setup & health tools

| Tool Name | Description | | --------- | ----------- | | get_server_configuration_status | Get the status of the MCP server | | test_cluster_connection | Check the cluster credentials by connecting to the cluster | | get_cluster_health_and_services | Get cluster health status and list of all running services |

Data model & schema discovery tools

| Tool Name | Description | | --------- | ----------- | | get_buckets_in_cluster | Get a list of all the buckets in the cluster | | get_scopes_in_bucket | Get a list of all the scopes in the specified bucket | | get_collections_in_scope | 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_scopes_and_collections_in_bucket | Get a list of all the scopes and collections in the specified bucket | | get_schema_for_collection | Get the structure for a collection |

Document KV operations tools

| Tool Name | Description | | --------- | ----------- | | get_document_by_id | Get a document by ID from a specified scope and collection | | upsert_document_by_id | Upsert a document by ID to a specified scope and collection. Disabled by default when CB_MCP_READ_ONLY_MODE=true. | | insert_document_by_id | Insert a new document by ID (fails if document exists). Disabled by default when CB_MCP_READ_ONLY_MODE=true. | | replace_document_by_id | Replace an existing document by ID (fails if document doesn't exist). Disabled by default when CB_MCP_READ_ONLY_MODE=true. | | delete_document_by_id | Delete a document by ID from a specified scope and collection. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |

Query and indexing tools

| Tool Name | Description | | --------- | ----------- | | list_indexes | List all indexes in the cluster with their definitions, with optional filtering by bucket, scope, collection and index name. Set return_raw_index_stats=true to return the unprocessed index information. | | get_index_advisor_recommendations | Get index recommendations from Couchbase Index Advisor for a given SQL++ query to optimize query performance | | run_sql_plus_plus_query | 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., SELECT * FROM users instead of SELECT * FROM bucket.scope.users).CB_MCP_READ_ONLY_MODE is true by default, which means that all write operations (KV and Query) are disabled. When enabled, KV write tools are not loaded and SQL++ queries that modify data are blocked. | | explain_sql_plus_plus_query | Generate and evaluate an EXPLAIN plan for a SQL++ query. Returns query metadata, extracted plan, and plan evaluation findings. |

Query performance analysis tools

| Tool Name | Description | | --------- | ----------- | | get_longest_running_queries | Get longest running queries by average service time | | get_most_frequent_queries | Get most frequently executed queries | | get_queries_with_largest_response_sizes | Get queries with the largest response sizes | | get_queries_with_large_result_count | Get queries with the largest result counts | | get_queries_using_primary_index | Get queries that use a primary index (potential performance concern) | | get_queries_not_using_covering_index | Get queries that don't use a covering index | | get_queries_not_selective | 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/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_MODE | --read-only-mode | Prevent all data modifications (KV and Query). When enabled, KV write tools are not loaded. | 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 | | CB_MCP_DISABLED_TOOLS | --disabled-tools | Tools to disable (see [Disabling Tools](#disabling-tools)) | None | | CB_MCP_CONFIRMATION_REQUIRED_TOOLS | --confirmation-required-tools | Tools that require explicit user confirmation before execution via MCP elicitation (see [Elicitation/Confirmation Required Tools](#elicitationconfirmation-for-tool-calls)) | None |

Read-Only Mode Configuration

CB_MCP_READ_ONLY_MODE is the single switch controlling write operations:

• When true (default): All write operations (KV and Query) are disabled. KV write tools (upsert, insert, replace, delete) are not loaded and will not be available to the LLM, and SQL++ queries that modify data or structure are blocked.
• When false: KV write tools are loaded and SQL++ data/structure modification queries are allowed.

This is the recommended safe default to prevent inadvertent data modifications by LLMs.

> 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.

Disabling Tools

You can disable specific tools to prevent them from being loaded and exposed to the MCP client. Disabled tools will not appear in the tool discovery and cannot be invoked by the LLM.

Supported Formats

Comma-separated list:

# 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

File path (one tool name per line):

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

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

File format (e.g., disabled_tools.txt):

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

Lines starting with # are treated as comments and ignored.

MCP Client Configuration Examples

Using comma-separated list:

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

Using file path (recommended for many tools):

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

Important Security Note

> Warning: Disabling tools alone does not guarantee that certain operations cannot be performed. The underlying database user's RBAC (Role-Based Access Control) permissions are the authoritative security control. > > For example, even if you disable upsert_document_by_id and delete_document_by_id, data modifications can still occur via the run_sql_plus_plus_query tool using SQL++ DML statements (INSERT, UPDATE, DELETE, MERGE) unless: > > - The CB_MCP_READ_ONLY_MODE is set to true (default), OR > - The database user lacks the necessary RBAC permissions for data modification > > Best Practice: Always configure appropriate RBAC permissions on your Couchbase user credentials as the primary security measure. Use tool disabling as an additional layer to guide LLM behavior and reduce the attack surface, not as the sole security control.

Elicitation/Confirmation for Tool Calls

You can require explicit user confirmation for specific tools before execution (when the MCP client supports elicitation).

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-tools supports these formats:

• Comma-separated list
• File path (one tool name per line, # comments supported)

Example:

# 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

When a listed tool is invoked:

• If the client supports elicitation, the user is prompted to confirm.
• If the client does not support elicitation, the tool executes without confirmation for backward compatibility.

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](#configuration) to the mcpServers section.

1. Restart Claude Desktop to apply the changes.

1. 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.

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

1. Specify the same [configuration](#configuration) manually, or use the one-click [Install in Cursor][cursor-install-basic] link. You may need to add the server configuration under a parent key of mcpServers.

> Note: The install link uses placeholder values from the configuration examples above. Update the connection string and credentials after installation.

1. Save the configuration.

1. You will see couchbase as an added server in MCP servers list. Refresh to see if server is enabled.

1. You can now use the Couchbase MCP server in Cursor to query your Couchbase cluster using natural language and perform CRUD operations on documents.

[cursor-install-basic]: htt

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: couchbase
• Source: couchbase/mcp-server-couchbase
• License: Apache-2.0
• Homepage: https://mcp-server.couchbase.com/

Install and usage instructions live in the source repository linked above.