Couchbase MCP Server

Official

Let AI agents securely connect to and work with data in Couchbase clusters

★ 34 Stars Category · Database Popular

72FMRS · B

A feature-complete, officially maintained database MCP server from Couchbase: cluster health, schema discovery, KV operations, SQL++ querying, index management, and performance analysis, with safe defaults (read-only), tool disabling, execution confirmation, OAuth 2.1, and thorough logging. Ideal for Couchbase users adding AI-driven data operations in mainstream MCP clients, but remember RBAC remains the authoritative security boundary.

Reliability

11/20

Security and permissions

16/20

Maintenance

13/20

Documentation

18/20

Setup experience

14/20

Read the FMRS scoring method →

An officially maintained, self-hosted MCP Server by Couchbase that allows AI agents to connect to Couchbase clusters — whether hosted on Capella or self-managed — and interact with their data. It provides tools across Cluster Health, Data Schema, Key-Value, Query, and Performance categories, with safety controls including read-only mode by default, fine-grained tool disabling, confirmation-required tools (client elicitation), OAuth 2.1 authorization (HTTP transport), and extensive logging configuration. Distributed via PyPI (couchbase-mcp-server), Docker, or source, it supports STDIO and Streamable HTTP transports (plus deprecated SSE).

Tools

get_server_configuration_status

Get server status and configuration without connecting to the cluster (read-only mode, disabled/confirmation-required tools, OAuth settings, resolved logging config)

test_cluster_connection

Check 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

List all buckets in the cluster

get_scopes_in_bucket

List all scopes in the specified bucket

get_collections_in_scope

List all collections in a specified scope and bucket (requires Query service)

get_scopes_and_collections_in_bucket

List all 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 in read-only mode

create_collection

Create a new collection in an existing scope (Couchbase Server 7.6+ and Capella); disabled by default in read-only mode

delete_scope

Delete a scope and all its collections — permanent; disabled by default in read-only mode

delete_collection

Delete a collection and all its documents — permanent; disabled by default in read-only mode

get_document_by_id

Get a document by ID from a specified scope and collection

sub_document_lookup_in

Look up parts of a document (fields, existence checks, 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 in read-only mode

insert_document_by_id

Insert a new document by ID (fails if it exists); disabled by default in read-only mode

replace_document_by_id

Replace an existing document by ID (fails if it doesn't exist); disabled by default in read-only mode

delete_document_by_id

Delete a document by ID from a specified scope and collection; disabled by default in read-only mode

sub_document_mutate_in

Modify parts of an existing document (upsert, insert, replace, remove, array ops, counters) by path; disabled by default in read-only mode

list_indexes

List all indexes in the cluster with definitions, with optional filtering and raw index stats

get_index_advisor_recommendations

Get index recommendations from Couchbase Index Advisor for a given SQL++ query

create_index

Create a scalar (non-vector) GSI secondary index, deferred by default; disabled by default in read-only mode

build_index

Trigger the build of all deferred indexes on a collection; disabled by default in read-only mode

drop_index

Drop a GSI index (scalar or vector) from a collection; disabled by default in read-only mode

run_sql_plus_plus_query

Run a SQL++ query on a specified scope; queries are auto-scoped to the bucket/scope; write queries are blocked in read-only mode (default)

explain_sql_plus_plus_query

Generate and evaluate an EXPLAIN plan for a SQL++ query, returning metadata, plan, and 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 far more documents than the final result)

Setup

Prerequisites: Python 3.10+, a running Couchbase cluster (Capella free tier is easiest), uv installed, and an MCP client such as Claude Desktop or Cursor. PyPI: add to mcpServers with command uvx and args ["couchbase-mcp-server"], setting CB_CONNECTION_STRING, CB_USERNAME, and CB_PASSWORD in env (for mTLS use CB_CLIENT_CERT_PATH and CB_CLIENT_KEY_PATH). Source: clone the repo and run uv --directory <repo-path> run src/mcp_server.py. A Docker image (docker.io/couchbase/mcp-server) is also available.

claude_desktop_config.json

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

Generate and validate client config

Fit and risk

Best for

Developers and data teams who want safe AI access to Couchbase data in mainstream MCP clients (Claude Desktop, Cursor, Windsurf, VS Code, JetBrains IDEs)
Teams already using Couchbase (Capella or self-managed) who want LLM-assisted querying and analysis

Not for

Unattended write access to production databases without risk assessment (read-only mode blocks writes by default)
Users not running Couchbase or without a running cluster
Those needing official support-portal assistance (community-maintained; GitHub only)

Required permissions

Couchbase connection string plus username/password for basic auth, or client certificate and key paths for mTLS, via environment variables or CLI arguments
CA root certificate path for TLS with self-signed/untrusted certificates on non-Capella clusters
Database user needs RBAC permissions to access at least one bucket — RBAC is the authoritative security control

Risks and side effects

CB_MCP_READ_ONLY_MODE defaults to true, disabling all writes; when false, the LLM can modify/delete documents, scopes, collections, and indexes
Disabling tools alone is not sufficient: SQL++ DML can still modify data via run_sql_plus_plus_query; use read-only mode or proper RBAC
delete_scope/delete_collection permanently destroy data
The HTTP endpoint is unauthenticated unless OAuth is configured
LLM outputs may be inaccurate; Couchbase does not review them and users are solely responsible
The product automatically collects usage/performance data (e.g., product version, IP address); see the Couchbase Privacy Policy

Troubleshooting

Verify the repo path in configuration when running from source (include trailing slash)
Check connection string, username, password, or certificate paths
For Capella, ensure the cluster is accessible from the machine running the MCP server (allowed IP list)
Confirm the database user has permissions for at least one bucket
Ensure uv is installed and accessible; use absolute paths to uv/uvx if needed
Check MCP client logs for errors; run uv sync after updating the source repo
Check the server version with uvx couchbase-mcp-server --version

Use cases

Query Couchbase data in natural language and perform document CRUD operations

Explore cluster structure and data models (buckets, scopes, collections, schema)

Analyze query performance bottlenecks and get index recommendations

Create and manage GSI secondary indexes

Supported clients

Claude DesktopFull support

CursorFull support

Windsurf EditorFull support

VS CodeFull support

JetBrains IDEsFull support

Related MCP servers

Compare with other MCP servers