Yes. The server is open source and free to run; you only pay for the Couchbase Server or Capella cluster it connects to.

Does it support remote/OAuth?

No. It runs locally over stdio (via uvx or Docker) and authenticates to the cluster with a connection string plus username/password, or mTLS client certificates. There is no hosted OAuth endpoint.

Is it official, and can the agent modify data?

It lives under the Couchbase Ecosystem organization but is community-maintained and not covered by official Couchbase support. Writes are off by default: CB_MCP_READ_ONLY_MODE is true unless you set it to false, which keeps the key-value write tools out of the agent's reach.

Couchbase MCP server

CommunityCouchbase32Config last verified Jun 1, 2026

Couchbase's MCP server lets an agent explore buckets, scopes, and collections, run SQL++ queries, and do key-value document operations.

The Couchbase MCP server, maintained under the Couchbase Ecosystem organization, connects an AI agent to data in a Couchbase cluster. The agent can map the data model end to end — list buckets, scopes, and collections and read a collection's structure — then work with documents through direct key-value operations (get, insert, upsert, replace, delete by ID) and run analytical SQL++ (N1QL) queries against a scope. It also exposes the query toolbox: list indexes, get Index Advisor recommendations for a SQL++ statement, and generate or evaluate an EXPLAIN plan, plus a suite of performance-analysis tools that surface the longest-running and most-frequent queries, the largest response sizes and result counts, and queries that use a primary index, miss a covering index, or are not selective. Connection-health tools round it out so the agent can verify credentials and inspect running services.

It is published to PyPI as couchbase-mcp-server and runs locally over stdio, launched with uvx (uvx couchbase-mcp-server) or via Docker, authenticating with CB_CONNECTION_STRING, CB_USERNAME, and CB_PASSWORD (mTLS is also supported). It works against Couchbase Server and Capella. A read-only mode is the default — CB_MCP_READ_ONLY_MODE is true unless you change it, which simply does not load the KV write tools — so handing a cluster to an agent for exploration carries no write risk out of the box. The project is Couchbase community-maintained and is not covered by official Couchbase support.

Quick install

Copy-paste configs are provided for all 8 supported clients. Pick your client below.

Add to ~/.claude.json

~/.claude.json

json

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": [
        "couchbase-mcp-server"
      ],
      "env": {
        "CB_CONNECTION_STRING": "<CB_CONNECTION_STRING>",
        "CB_USERNAME": "<CB_USERNAME>",
        "CB_PASSWORD": "<CB_PASSWORD>"
      }
    }
  }
}

Or via CLI

bash

claude mcp add couchbase -- uvx couchbase-mcp-server

Step-by-step guides

Available tools

Tool	Description
get_server_configuration_status	Gets the status of the MCP server.
test_cluster_connection	Checks the cluster credentials by connecting to the cluster.
get_cluster_health_and_services	Gets cluster health status and the list of running services.
get_buckets_in_cluster	Lists all buckets in the cluster.
get_scopes_in_bucket	Lists all scopes in a specified bucket.
get_collections_in_scope	Lists all collections in a specified scope and bucket.
get_scopes_and_collections_in_bucket	Lists all scopes and collections in a specified bucket.
get_schema_for_collection	Gets the inferred structure of a collection.
get_document_by_id	Gets a document by ID from a specified scope and collection.
upsert_document_by_id	Upserts a document by ID into a specified scope and collection.
insert_document_by_id	Inserts a new document by ID; fails if the document already exists.
replace_document_by_id	Replaces an existing document by ID; fails if it does not exist.
delete_document_by_id	Deletes a document by ID from a specified scope and collection.
list_indexes	Lists all indexes in the cluster with their definitions.
get_index_advisor_recommendations	Gets Index Advisor recommendations for a given SQL++ query.
run_sql_plus_plus_query	Runs a SQL++ (N1QL) query on a specified scope.
explain_sql_plus_plus_query	Generates and evaluates an EXPLAIN plan for a SQL++ query.
get_longest_running_queries	Gets the longest-running queries by average service time.
get_most_frequent_queries	Gets the most frequently executed queries.
get_queries_with_largest_response_sizes	Gets the queries with the largest response sizes.
get_queries_with_large_result_count	Gets the queries with the largest result counts.
get_queries_using_primary_index	Gets queries that use a primary index.
get_queries_not_using_covering_index	Gets queries that do not use a covering index.
get_queries_not_selective	Gets queries that are not selective.

Required configuration

CB_CONNECTION_STRINGRequired
Connection string to the Couchbase cluster.
CB_USERNAMERequired
Couchbase database username (or use mTLS cert/key paths).
CB_PASSWORDRequired
Password for the Couchbase user.
CB_CA_CERT_PATHOptional
Path to a CA certificate for TLS verification. Optional.
CB_MCP_READ_ONLY_MODEOptional
When true (the default), KV write tools are not loaded. Set to false to enable writes.

What you can do with it

Explore a cluster read-only

In the default read-only mode the agent maps buckets, scopes, and collections, infers schema, and runs SQL++ queries to answer questions — with no document-write tools loaded, so there is no write risk.

Diagnose slow queries

Use the performance tools to surface the longest-running and most-frequent queries and those missing a covering index, then get Index Advisor recommendations and an EXPLAIN plan to guide a fix.

FAQ

Is it free?: Yes. The server is open source and free to run; you only pay for the Couchbase Server or Capella cluster it connects to.
Does it support remote/OAuth?: No. It runs locally over stdio (via uvx or Docker) and authenticates to the cluster with a connection string plus username/password, or mTLS client certificates. There is no hosted OAuth endpoint.
Is it official, and can the agent modify data?: It lives under the Couchbase Ecosystem organization but is community-maintained and not covered by official Couchbase support. Writes are off by default: CB_MCP_READ_ONLY_MODE is true unless you set it to false, which keeps the key-value write tools out of the agent's reach.

← Browse all databases servers