Couchbase MCP Server

Let LLMs query Couchbase clusters, run SQL++, manage documents, and analyze query performance.

Unverified

stdio (local)

API key

Python

View repo 32 Website

Add to your client

Copy the config for your MCP client and paste it into its config file.

Install / run

uvx couchbase-mcp-server

Paste into ~/Library/Application Support/Claude/claude_desktop_config.json

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

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf

Before you start

Python 3.10 or higher
A running Couchbase cluster (e.g. Capella free tier or self-hosted Couchbase Server)
uv installed to run the server
An MCP client such as Claude Desktop, Cursor, Windsurf, VS Code, or JetBrains IDEs
Couchbase credentials: username/password (basic auth) or client certificate and key (mTLS)

About Couchbase MCP Server

An MCP server implementation for Couchbase that allows LLMs to directly interact with Couchbase clusters. It provides tools across cluster setup and health, data-model and schema discovery, document KV operations, SQL++ querying and indexing, and query performance analysis. Distributed as a PyPI package and a Docker image, it runs over stdio by default and also supports Streamable HTTP and deprecated SSE transports.

Tools & capabilities (24)

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.

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. Requires the cluster to have the 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.

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.

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 unprocessed index information.

get_index_advisor_recommendations

Get index recommendations from the 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. With CB_MCP_READ_ONLY_MODE=true (default), data-modifying SQL++ queries 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.

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 the final result).

What this server can do

Couchbase MCP Server provides tools for these capabilities — tap one to see every MCP server that does the same:

Execute SQL Inspect database schema

When to use it

Query Couchbase data with natural language via SQL++ from an AI assistant
Explore cluster structure: buckets, scopes, collections, and inferred document schemas
Perform document CRUD operations by ID against scopes and collections
Get index advisor recommendations and EXPLAIN plans to optimize slow queries
Analyze query performance to find longest-running, most frequent, or non-selective queries

Security notes

CB_MCP_READ_ONLY_MODE defaults to true, disabling all KV and SQL++ write operations. Disabling individual tools does not by itself prevent data modification (e.g. SQL++ DML via run_sql_plus_plus_query); the Couchbase user's RBAC permissions are the authoritative security control and should be scoped appropriately. Streamable HTTP and SSE transport modes do not include authorization support.

Couchbase MCP Server FAQ

Is it safe to let an LLM modify my data?

By default CB_MCP_READ_ONLY_MODE is true, which disables all KV and SQL++ write operations. To allow writes, set it to false. Note that the Couchbase user's RBAC permissions are the authoritative security control, so scope your credentials appropriately.

How do I authenticate?

You can use basic authentication with CB_CONNECTION_STRING, CB_USERNAME, and CB_PASSWORD, or mTLS using CB_CLIENT_CERT_PATH and CB_CLIENT_KEY_PATH. If both are provided, the client certificate is used.

Which transports are supported?

stdio (default), Streamable HTTP, and SSE (deprecated). HTTP and SSE modes do not include authorization support. Set the mode via CB_MCP_TRANSPORT or --transport.

Which MCP clients are supported?

The README provides setup instructions for Claude Desktop, Cursor, Windsurf Editor, VS Code, and JetBrains IDEs, and notes that other MCP clients can be used as well.

Can I run it without installing Python locally?

Yes. A prebuilt Docker image is available on Docker Hub (docker.io/couchbase/mcp-server) and the Docker MCP Catalog, and can be used in stdio mode via a docker run command in the MCP client config.

#couchbase #database #nosql #sql++#capella #kv-store #query

Alternatives to Couchbase MCP Server

Compare all alternatives →

MCP Toolbox for Databases (BigQuery)

Databases

16k

Google's official MCP server with prebuilt BigQuery tools, querying datasets via Application Default Credentials.

Verified

stdio (local)

OAuth

10 tools

Updated 23 days agoRepo

InstantDB MCP

Databases

10k

Create, manage, and query your InstantDB apps, schemas, permissions, and data from your AI editor.

Unverified

HTTP (remote)

OAuth

TypeScript

7 tools

Updated 1 day agoRepo

DBHub

Databases

3.0k

Zero-dependency, token-efficient database MCP server for Postgres, MySQL, SQL Server, MariaDB, and SQLite.

Unverified

stdio (local)

No auth

TypeScript

3 tools

Updated 1 day agoRepo

Compare Couchbase MCP Server with:

vs MCP Toolbox for Databases (BigQuery)vs InstantDB MCP vs DBHub vs Postgres MCP Pro