Couchbase MCP Server

The Couchbase MCP Server connects AI assistants such as Claude, Cursor, Windsurf, or VS Code to Couchbase clusters. Anyone using Couchbase as an application database can ask their assistant which buckets, scopes, and collections exist, how documents are structured, or why a query runs slowly, without switching between the editor, a query tool, and the admin interface. The server is developed in the repository couchbase/mcp-server-couchbase, is licensed under Apache 2.0, and according to the vendor works with both Couchbase Capella and self-managed clusters.

What is the Couchbase MCP Server?

It is a self-hosted server that you run locally or in your own environment. It is distributed as a Python package on PyPI and started with uvx couchbase-mcp-server; alternatively there is a Docker image and a build from source. According to the README the prerequisites are Python 3.10 or newer and the uv tool. The default transport is stdio, and Streamable HTTP is supported as well, for example to run it as a shared service. The connection to the cluster is configured through environment variables such as CB_CONNECTION_STRING, CB_USERNAME, and CB_PASSWORD; for TLS connections to self-managed clusters, certificate paths are added.

Which tools are available?

The documentation groups the tools into several areas. Exploration covers cluster health and schema discovery for buckets, scopes, and collections. Documents can be read, created, replaced, and deleted through key-value access, including partial sub-document changes. For queries there is SQL++, plus index management with the Index Advisor, which suggests indexes, and tools to analyze query performance, such as the slowest or most frequent queries. Full-text and vector search are included as well as a separate set of operational-insights tools. According to the README some features require newer server versions, for example the search tools from 7.6, and a few tools exist only for self-managed clusters, not for Capella.

What is it particularly useful for?

The greatest value lies in everyday development work: the assistant reads the schema, writes fitting SQL++ queries, checks results, and proposes indexes when a query scans too many documents. For performance problems it can evaluate the slowest queries and give hints. Compared with a generic database server, this server knows concepts such as scopes, collections, the Index Advisor, and Couchbase's search services, and therefore returns answers that fit the platform.

Security: read-only mode by default

According to the vendor the server is "safe by default": CB_MCP_READ_ONLY_MODE is set to true by default. In that case writing tools are not loaded, and SQL++ statements that change data or structures are blocked. The writing tools include creating and deleting scopes and collections, changing and deleting documents, creating and dropping indexes, and cancelling running queries. With CB_MCP_DISABLED_TOOLS you can switch off individual tools, and with CB_MCP_CONFIRMATION_REQUIRED_TOOLS you require explicit confirmation for selected tools, provided the client supports that prompt. The documentation stresses that disabling tools is not a guarantee: the access rights of the database user remain decisive. Therefore create a dedicated user with minimal rights.

Support and maturity

The vendor's statements are not entirely consistent here. The README describes the project as maintained by the Couchbase community and not officially supported by the support team; inquiries should go through GitHub. The project page with the documentation, on the other hand, names enterprise support as part of a Couchbase AI Data Plane license. Which arrangement applies to you is best clarified with Couchbase. The repository was last updated on 16 October 2026 and is not archived; it has 34 GitHub stars.

Costs

The server itself is open source and free. Costs can arise for the database: according to the Capella documentation there is a free operational cluster to get started, above it paid Capella plans, and a self-managed server edition. You will find current terms on Couchbase's official pricing page; it could not be retrieved during the review and is therefore not described in detail here.

Who is the Couchbase MCP Server for?

It is worthwhile for development teams that already use Couchbase and want their assistant to understand schema, queries, and indexes. If you have no Couchbase data you do not need it: the server is not a database of its own but an access path to an existing cluster. Begin in read-only mode and with a user who may only read the buckets that are needed.

A reachable Couchbase cluster (Capella or self-managed) with credentials, Python 3.10 or newer, the uv tool, and an MCP client such as Claude Code or Cursor.

With the Couchbase MCP Server an AI assistant explores your Couchbase cluster and runs SQL++ queries. This guide leads from the prerequisites to the first query.

Step 1: Check the prerequisites

You need a reachable Couchbase cluster (Capella or self-managed), Python 3.10 or newer, and the uv tool. According to the README some features, such as the search tools, require server 7.6 or newer.

Step 2: Create a dedicated database user

Create a user in the cluster who may read only the buckets the assistant should see. The documentation stresses that the database user's rights remain decisive even when tools are switched off in the server.

Step 3: Add it to Claude or Cursor

Under mcpServers add an entry with "command": "uvx" and "args": ["couchbase-mcp-server"]. In the env field pass CB_CONNECTION_STRING, CB_USERNAME, and CB_PASSWORD. VS Code uses the key servers instead of mcpServers. For self-managed clusters with TLS, the path CB_CA_CERT_PATH is added.

Keep read-only mode

CB_MCP_READ_ONLY_MODE is true by default: writing tools are not loaded, and SQL++ statements that change data are blocked. Switch it off only if the assistant should really change documents or indexes, and then check CB_MCP_CONFIRMATION_REQUIRED_TOOLS for confirmation prompts before risky tools.

Step 4: Run as a shared service

Instead of stdio the server supports Streamable HTTP through CB_MCP_TRANSPORT, CB_MCP_HOST, and CB_MCP_PORT; the documentation also describes OAuth 2.1 for this. Alternatively use the Docker image couchbase/mcp-server.

Step 5: First queries

Start with "Which buckets, scopes, and collections exist?" and then, for example, "Show the structure of the orders collection" or "Which queries run the slowest?" Check generated SQL++ queries before drawing conclusions from them.

uvx couchbase-mcp-server

Couchbase cluster username and password via environment variables; optionally mTLS certificates and OAuth 2.1 when running over Streamable HTTP.

By default read-only on schema, documents, and queries; with CB_MCP_READ_ONLY_MODE=false also writing, deleting, and index management within the database user's rights.

The server runs in your own environment. Retrieved documents and query results enter the AI client context and therefore reach the model provider.

A disabled read-only mode combined with broad database rights, credentials in the client configuration, and sensitive documents that reach the model provider.