Couchbase MCP Server

Couchbase MCP Server is a self-hosted MCP Server that allows AI agents to connect to and interact with data in Couchbase clusters, whether hosted on Capella or self-managed. It provides tools across categories including Cluster Health, Data Schema, Key-Value, Query, and Performance — with safety controls via read-only mode and fine-grained tool disabling. It supports both STDIO and Streamable HTTP transports.

Couchbase MCP server is distributed as a Python Package Index (PyPI) package and via Docker. Enterprise support for Couchbase MCP Server is available by licensing Couchbase AI Data Plane, which also entitles use and enterprise support of Couchbase Agent Memory and Couchbase Agent Catalog.

[][cursor-install-basic]

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

Features/Tools

Cluster setup & health tools

Tool Name	Description
`get_server_configuration_status`	Get the server status and configuration without connecting to the cluster — reports read-only mode, disabled/confirmation-required tools, OAuth settings, and the resolved logging configuration
`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
`get_cluster_diagnostics_report`	Get the SDK's cached connection diagnostics — whether connections were already broken and for how long, without any active network probing

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
`create_scope`	Create a new scope in a bucket (Couchbase Server 7.6+ and Capella). Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.
`create_collection`	Create a new collection in an existing scope (Couchbase Server 7.6+ and Capella). Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.
`delete_scope`	Delete a scope and all its collections from a bucket — permanent. Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.
`delete_collection`	Delete a collection and all its documents from a scope — permanent. Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.

Document KV operations tools

Tool Name	Description
`get_document_by_id`	Get a document by ID from a specified scope and collection
`lookup_subdocument`	Look up parts of a document (specific fields, existence checks, or array/object counts) by path without fetching the whole document
`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`.
`mutate_subdocument`	Modify parts of an existing document (upsert, insert, replace, remove, array ops, counters) by path without rewriting the whole document. 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
`create_index`	Create a scalar (non-vector) GSI secondary index on a collection. Deferred by default — call `build_index` afterward to build it. Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.
`build_index`	Trigger the build of all deferred indexes on a collection. Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.
`drop_index`	Drop a GSI index (scalar or vector) from a collection. Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.
`run_sql_plus_plus_query`	Run a SQL++ query on a specified scope.<br><br>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`).<br><br>`CB_MCP_READ_ONLY_MODE` is `true` by default, which means that all write operations (KV, Query, scope/collection management, and index management) are disabled. When enabled, KV, collection management, and index 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"
      }
    }
  }
}

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

…

Server Couchbase

Installation

Configuration

How to use

README

Couchbase MCP Server

Features/Tools

Cluster setup & health tools

Data model & schema discovery tools

Document KV operations tools

Query and indexing tools

Query performance analysis tools

Prerequisites

Configuration

Running from PyPI

Server Configuration using Pre built Package for MCP Clients

Basic Authentication

mTLS

Running from Source

Clone the repository to your local machine

Server Configuration using Source for MCP Clients

You might also like