MCP Server Couchbase

What Couchbase-Ecosystem/mcp-server-couchbase MCP server does

Couchbase-Ecosystem/mcp-server-couchbase MCP server gives AI assistants an MCP interface to Couchbase clusters. The same server can connect to Couchbase Capella or a self-managed Couchbase Server deployment. It supports inspection of cluster structure and health, document reads and writes, SQL++ execution, and natural-language analysis of query performance.

The server is intended for MCP clients such as Claude Desktop, Cursor, Windsurf, VS Code Copilot, and other clients that implement the MCP specification. It is useful when developers want an assistant to inspect buckets and collections, investigate cluster status, run controlled data queries, or review slow queries without building a separate application integration.

How it works

The server implements the Model Context Protocol and presents Couchbase operations as callable tools. These tools are grouped around cluster setup and health, data-model discovery, key-value access, queries, and performance. Example workflows include listing buckets, scopes, and collections; examining a collection’s structure; checking service health; running SQL++; and identifying slow queries or possible index issues.

Couchbase permissions remain the primary security boundary. The server also provides behavior controls for AI-driven access. Read-only mode blocks document inserts, updates, deletes, and data-modifying SQL++ statements unless it is explicitly disabled. Individual tools can also be disabled or configured to require confirmation.

Two transport modes are available. STDIO is intended for local desktop clients, while Streamable HTTP supports shared or remote deployments. Streamable HTTP can use OAuth 2.1 authorization with JWT/JWKS validation and is described as provider-agnostic, including providers such as Auth0, Okta, Keycloak, Entra, and Cognito.

Setup and configuration

Couchbase-Ecosystem/mcp-server-couchbase MCP server is distributed as a Python package on PyPI and is also available as a Docker image. The project identifies Python 3.10 or newer as supported. Configuration must provide access to the target Couchbase cluster, whether that cluster is hosted in Capella or managed independently.

The CB_MCP_READ_ONLY_MODE setting controls write protection. The documented default is read-only mode enabled; setting CB_MCP_READ_ONLY_MODE=false permits write operations, subject to the Couchbase user’s RBAC permissions and any per-tool restrictions. The README also documents configuration for disabled tools, confirmation-gated tools, logging, and OAuth settings.

For local use, configure an MCP client to launch the server over STDIO. For networked use, run it with Streamable HTTP and configure the client and, if needed, an OAuth 2.1 identity provider. Docker is an alternative distribution method. The repository links to the project documentation for client-specific configuration and deployment details.

Tools and capabilities

The documented tool areas include:

• Checking server configuration, cluster credentials, health, running services, and cached connection diagnostics.
• Listing buckets, scopes, and collections, including combined scope and collection discovery.
• Inspecting collection structure and schema information.
• Reading and modifying Couchbase documents through key-value operations, subject to safety controls.
• Running SQL++ queries, including read queries and explicitly permitted data-modifying statements.
• Reviewing query performance and investigating slow queries or indexing concerns.

Limitations and notes

The tool-disabling layer guides agent behavior but does not replace Couchbase RBAC. The Couchbase account’s assigned roles determine the underlying access available to the server. Some schema operations have cluster requirements; for example, collection discovery requires the Query service, and scope creation is documented for Couchbase Server 7.6 and newer and Capella.

Enterprise support is tied to a Couchbase AI Data Plane license. The project is otherwise presented as an Apache-2.0-licensed package. OAuth is relevant to Streamable HTTP deployments, not necessarily to local STDIO usage.