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.
“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.”
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.
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.
DOCUMENTED COMMAND
uvx couchbase-mcp-server 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"
}
}
}
} 04 / FOLLOW THE EVIDENCE
The source trail.
Our notes are separate from the original resource.
Check upstream before adopting a new version.
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
https://github.com/couchbase/mcp-server-couchbase/blob/6d4266f9066e629a95c062d32cb8b7d093d2fb60/pyproject.toml
Supports: language, license
https://github.com/couchbase/mcp-server-couchbase/blob/6d4266f9066e629a95c062d32cb8b7d093d2fb60/LICENSE
Supports: license
https://docs.couchbase.com/mcp-server/get-started/overview.html
Supports: compatibility, bestFor