---
title: "Couchbase MCP Server: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/mcp-servers/couchbase/
description: "Self-hosted Couchbase server with cluster health, schema, key-value, SQL++ and performance tools. Read-only mode is on by default, individual tools can be disabled, and the underlying Couchbase RBAC remains the authoritative boundary across stdio, Streamable HTTP and SSE transports."
---

# Couchbase MCP Server: review, setup & limitations · Undominated.ai

> Self-hosted Couchbase server with cluster health, schema, key-value, SQL++ and performance tools. Read-only mode is on by default, individual tools can be disabled, and the underlying Couchbase RBAC remains the authoritative boundary across stdio, Streamable HTTP and SSE transports.

[← Explore all mcp servers](/mcp-servers/)

DATABASE EXPLORATION / Couchbase

# Couchbase MCP Server

Self-hosted Couchbase server with cluster health, schema, key-value, SQL++ and performance tools. Read-only mode is on by default, individual tools can be disabled, and the underlying Couchbase RBAC remains the authoritative boundary across stdio, Streamable HTTP and SSE transports.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/couchbase/mcp-server-couchbase)

SOURCE REVIEW

 Reviewed 2026-10-13
 Evidence 4 linked sources
 Publisher Couchbase
 Licence [Apache-2.0 ↗](https://github.com/couchbase/mcp-server-couchbase/blob/6d4266f9066e629a95c062d32cb8b7d093d2fb60/LICENSE)
 Revision 6d4266f9066e
 [Read what was—and wasn’t—checked ↓](#review)

“Couchbase MCP Server is a self-hosted Model Context Protocol (MCP) server that connects AI agents and LLM-powered assistants — Claude, Cursor, Windsurf, VS Code Copilot, and other MCP clients — to data in Couchbase clusters, whether hosted on Capella or self-managed.”

 [Couchbase · upstream description ↗](https://github.com/couchbase/mcp-server-couchbase/blob/6d4266f9066e629a95c062d32cb8b7d093d2fb60/README.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - Couchbase publishes the server in its own organisation as a Production-status PyPI package with read-only mode enabled by default.
- It is the only screened server this wave offering optional OAuth 2.1 (JWT/JWKS, provider-agnostic) on its HTTP transport for shared deployments, alongside per-tool disabling.

### A good fit for

 - Exploring buckets, scopes, collections and schemas and running SQL++ queries on Capella or self-managed clusters from an assistant.
- Teams that need a shared remote deployment with authentication in front, rather than a per-desktop stdio process.

### Weigh up before choosing

 - The product automatically collects usage and performance data including IP address, stated in the README's Usage Data Collection section.
- Tool disabling is a convenience layer for guiding LLM behaviour; the connecting Couchbase user's RBAC remains the authoritative security boundary.
- Setting CB_MCP_READ_ONLY_MODE=false loads every write tool at once, including delete_scope and delete_collection, which the README calls permanent, and lets SQL++ queries modify data or structure.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - README.md at pinned revision 6d4266f9066e629a95c062d32cb8b7d093d2fb60: tool categories, CB_MCP_READ_ONLY_MODE default, transport modes including Streamable HTTP and SSE with optional OAuth 2.1, PyPI and Docker distribution, usage data collection statement.
- pyproject.toml at the same revision: couchbase-mcp-server 1.0.2rc5, Python >=3.10,<3.15, Apache-2.0, Couchbase Inc. authorship, Production status classifier, entrypoint couchbase-mcp-server = mcp_server:main.
- LICENSE at the same revision: Apache License 2.0.

### Our findings

 - Write operations (document upserts, inserts, deletes and data-modifying SQL++) are blocked unless CB_MCP_READ_ONLY_MODE=false is set explicitly.
- The distribution ships two servers: the operational server by default and a separate operational insights server.
- The README’s Read-Only Mode section lists the write tools that load only when CB_MCP_READ_ONLY_MODE=false: upsert_document_by_id, insert_document_by_id, replace_document_by_id, delete_document_by_id, mutate_subdocument, create_scope, create_collection, delete_scope, delete_collection, create_index, build_index, drop_index, upsert_fts_index, drop_fts_index.
- CB_MCP_CONFIRMATION_REQUIRED_TOOLS or --confirmation-required-tools makes named tools ask the user to confirm before they run, when the client supports MCP elicitation.
- Authentication is a username and password or a client certificate and key for mTLS. The README says certificates are used when both are given.

### Not established by this review

 - The server was not installed or connected to a cluster; no SQL++ query or document operation was executed.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Connect a server deliberately.

[Upstream setup instructions ↗](https://github.com/couchbase/mcp-server-couchbase/blob/6d4266f9066e629a95c062d32cb8b7d093d2fb60/README.md)

DOCUMENTED COMMAND

 uvx couchbase-mcp-server Copy command ↗

Copying does not execute this command. It may retrieve a newer version than the reviewed source.

 - Run the prebuilt PyPI package with uvx or the published Docker image.
- Configure CB_CONNECTION_STRING, CB_USERNAME and CB_PASSWORD for the target cluster.
- Keep read-only mode on unless write tools are intended, and disable individual tools that are not needed.

### Before you start

 - Python 3.10+ with uv, or Docker.
- A Couchbase Capella or self-managed cluster with credentials.

### Documented configuration example

Use the client and authentication context described in the setup guidance. Configuration formats vary between hosts.

 {
 "mcpServers": {
 "couchbase": {
 "command": "uvx",
 "args": [
 "couchbase-mcp-server"
 ],
 "env": {
 "CB_CONNECTION_STRING": "YOUR_COUCHBASE_CONNECTION_STRING",
 "CB_USERNAME": "YOUR_COUCHBASE_USERNAME",
 "CB_PASSWORD": "YOUR_COUCHBASE_PASSWORD"
 }
 }
 }
} Copy configuration ↗

### Compatibility

MCP clients supporting stdio, Streamable HTTP or SSE; tested with Claude Desktop, Cursor, Windsurf, VS Code and JetBrains AI Assistant. · A Couchbase Capella or self-managed cluster with connection string and credentials.

### Implementation

Python

### Transports

stdio · Streamable HTTP · SSE

### Couchbase cluster credentials

 - Read-only mode is on by default; writes require CB_MCP_READ_ONLY_MODE=false and are still bounded by the connecting user's RBAC roles.
- Streamable HTTP deployments can require OAuth 2.1 with JWT/JWKS from any provider.
- Authenticates to the cluster with CB_USERNAME and CB_PASSWORD, or with CB_CLIENT_CERT_PATH and a key for mTLS

### Cost model

Open source under Apache-2.0; enterprise support is licensed separately through Couchbase AI Data Plane.

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [Couchbase MCP Server readme at pinned revision ↗](https://github.com/couchbase/mcp-server-couchbase/blob/6d4266f9066e629a95c062d32cb8b7d093d2fb60/README.md) Checked 2026-10-13 https://github.com/couchbase/mcp-server-couchbase/blob/6d4266f9066e629a95c062d32cb8b7d093d2fb60/README.md Supports: summary, upstreamDescription, install, configExample, access, transports, whySelected, bestFor, limitations, Write tool list, Confirmation-required tools, Authentication by password or mTLS, review
- [pyproject.toml manifest at pinned revision ↗](https://github.com/couchbase/mcp-server-couchbase/blob/6d4266f9066e629a95c062d32cb8b7d093d2fb60/pyproject.toml) Checked 2026-10-13 https://github.com/couchbase/mcp-server-couchbase/blob/6d4266f9066e629a95c062d32cb8b7d093d2fb60/pyproject.toml Supports: language, license
- [Repository licence at pinned revision ↗](https://github.com/couchbase/mcp-server-couchbase/blob/6d4266f9066e629a95c062d32cb8b7d093d2fb60/LICENSE) Checked 2026-10-13 https://github.com/couchbase/mcp-server-couchbase/blob/6d4266f9066e629a95c062d32cb8b7d093d2fb60/LICENSE Supports: license
- [Couchbase MCP Server documentation ↗](https://docs.couchbase.com/mcp-server/get-started/overview.html) Checked 2026-10-07 https://docs.couchbase.com/mcp-server/get-started/overview.html Supports: compatibility, bestFor

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### AWS Labs MCP Server for Oracle Database ↗ Pins the Oracle server whose README defaults to read-only SQL and keeps the secret ARN off the tool surface.](/mcp-servers/awslabs-oracle/)[### MongoDB MCP Server ↗ Provides MongoDB database and Atlas operations through a local server with an explicit read-only startup option.](/mcp-servers/mongodb/)[### Neo4j MCP ↗ Explore a Neo4j graph schema and run Cypher through a server with an explicit read-only configuration.](/mcp-servers/neo4j/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Inspect resource evidence](/tools/)
- [Choose a host](/agents/)
- [Inspect reusable workflows](/skills/)
- [Use Undominated data](/api/)
