MCP SERVER · OFFICIAL PROJECTRun SQL++ against a Couchbase cluster, read documents by key or by path, and see which queries are hurting.
LABSCO SUMMARY
The query-monitoring tools are the part you will not find on most database servers: seven separate reads of the completed_requests catalog that surface unselective queries, missing covering indexes and primary-index scans, with the Index Advisor available on any statement you paste in. Writes exist across documents, collections and indexes, but they stay switched off until you set the read-only flag to false, and individual tools can be disabled or made to ask first.
A Couchbase server spanning three surfaces: cluster and collection structure, key-value document access, and SQL++ with the query monitoring catalog behind it.
A Couchbase cluster and credentials: CB_CONNECTION_STRING plus either CB_USERNAME and CB_PASSWORD, or the mTLS pair CB_CLIENT_CERT_PATH and CB_CLIENT_KEY_PATH. Self-signed clusters also need CB_CA_CERT_PATH; Capella does not. Installed from PyPI as couchbase-mcp-server, stdio by default, with http and sse available through CB_MCP_TRANSPORT plus CB_MCP_HOST and CB_MCP_PORT. CB_MCP_READ_ONLY_MODE is true by default — every write tool stays unloaded and data-modifying SQL++ is blocked until you turn it off. CB_MCP_DISABLED_TOOLS and CB_MCP_CONFIRMATION_REQUIRED_TOOLS narrow the surface further, the latter needing a client that supports elicitation.
One command plus credentials — uvx couchbase-mcp-server, then supply credentials
USE CASES
Walk buckets, scopes and collections, then infer the schema of the collection you care about before querying it.
Run the query scoped to its bucket and scope, then read the EXPLAIN plan if the result comes back slowly.
Pull the longest-running and most frequent queries, then check which of them scan a primary index or miss a covering one.
List what already exists, then get Index Advisor recommendations for the exact statement that is slow.
Look up the path instead of fetching the whole document — the same call does existence checks and array counts.
Read health and running services, test the credentials against the bucket, and look at the SDK's cached connection diagnostics.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
explain_sql_plus_plus_queryGenerate and evaluate an EXPLAIN plan for a SQL++ query. It provides information about the execution plan for the query.
The EXPLAIN statement is run in the specified scope in the specified bucket. It returns query metadata along with an extracted plan and plan evaluation.
get_buckets_in_clusterGet the names of all the accessible buckets in the cluster.
get_cluster_health_and_servicesGet cluster health status and list of all running services.
This tool provides health monitoring by:
If bucket_name is provided, it actively pings services from the perspective of the bucket. Otherwise, it uses cluster-level ping to get the health status of the cluster.
Returns:
get_collections_in_scopeGet the names of all collections in the given scope and bucket.
get_document_by_idGet a document by its ID from the specified scope and collection. If the document is not found, it will raise an exception.
get_index_advisor_recommendationsGet index recommendations from Couchbase Index Advisor for a given SQL++ query.
The Index Advisor analyzes the query and provides recommendations for optimal indexes. This tool works with SELECT, UPDATE, DELETE, or MERGE queries. The queries will be run on the specified scope in the specified bucket.
Returns a dictionary with:
Each index object contains:
get_longest_running_queriesGet the N longest running queries from the system:completed_requests catalog.
get_most_frequent_queriesGet the N most frequent queries from the system:completed_requests catalog.
get_queries_not_selectiveGet queries that are not very selective from the system:completed_requests catalog.
get_queries_not_using_covering_indexGet queries that don't use a covering index from the system:completed_requests catalog.
get_queries_using_primary_indexGet queries that use a primary index from the system:completed_requests catalog.
get_queries_with_large_result_countGet queries with the largest result counts from the system:completed_requests catalog.
get_queries_with_largest_response_sizesGet queries with the largest response sizes from the system:completed_requests catalog.
get_schema_for_collectionGet the schema for a collection in the specified scope. Returns a dictionary with the collection name and the schema returned by running INFER query on the Couchbase collection.
get_scopes_and_collections_in_bucketGet the names of all scopes and collections in the bucket. Returns a dictionary with scope names as keys and lists of collection names as values.
get_scopes_in_bucketGet the names of all scopes in the given bucket.
get_server_configuration_statusGet the server status and configuration without establishing connection. This tool can be used to verify if the server is running and check the configuration.
list_indexesList indexes in the cluster with optional filtering by bucket, scope, collection, and index name.
Filters must be provided hierarchically: scope requires bucket, collection requires both, index requires all three. Set `return_raw_index_stats=True` to get the unprocessed source row for each index.
Each result contains: name, definition (CREATE INDEX statement), status, isPrimary, bucket, scope, collection, lastScanTime. If a required field is missing, the entry contains warning and raw_index_stats instead.
Source depends on cluster version: v8+ queries `system:indexes via the query service (RBAC-scoped — the connected user sees only indexes on keyspaces they can access); older clusters fall back to the admin-level Index Service REST API /getIndexStatus`.
run_sql_plus_plus_queryRun a SQL++ query on a scope and return the results as a list of JSON objects.
The query will be run on the specified scope in the specified bucket. The query should use collection names directly without bucket/scope prefixes, as the scope context is automatically set.
Use `named_parameters to bind values to $name` placeholders in the query instead of concatenating user input into the statement. This prevents SQL++ injection
Example: query = "SELECT * FROM users WHERE age > 18" # Incorrect: "SELECT * FROM bucket.scope.users WHERE age > 18"
test_cluster_connectionTest the connection to Couchbase cluster and optionally to a bucket. This tool verifies the connection to the Couchbase cluster and bucket by establishing the connection if it is not already established. If bucket name is not provided, it will not try to connect to the bucket specified in the MCP server settings. Returns connection status and basic cluster information.
BEFORE YOU INSTALL
20 tools when we connected; the project documents 34. CB_MCP_READ_ONLY_MODE is true by default, which hides the twelve write tools (scope, collection, document and index changes). CB_MCP_DISABLED_TOOLS can remove further named tools.
All 3 documented clients run the server on your machine.
INSTALLATION
uvx couchbase-mcp-server{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": [
"couchbase-mcp-server"
],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "<YOUR_CB_USERNAME>",
"CB_PASSWORD": "<YOUR_CB_PASSWORD>"
}
}
}
}{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": [
"couchbase-mcp-server"
],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_CLIENT_CERT_PATH": "<YOUR_CB_CLIENT_CERT_PATH>",
"CB_CLIENT_KEY_PATH": "<YOUR_CB_CLIENT_KEY_PATH>"
}
}
}
}MCP servers
1RB
kpritam
redis
manpreet2000