Couchbase MCP Server
Official Couchbase MCP server: the agent inspects schemas, finds documents and builds SQL++, read-only by default
- 34 ★ on the repository
- Last commit
Extended access
Why this level
- The agent runs SQL++ queries with the database user's rights and, with writes enabled, can change and delete documents
- The product sends usage data to Couchbase
Install
- Works in
Manual install
{"mcpServers":{"couchbase":{"command":"uvx","args":["couchbase-mcp-server","operational"],"env":{"CB_CONNECTION_STRING":"couchbases://connection-string","CB_USERNAME":"username","CB_PASSWORD":"password"}}}}Run from PyPI; uv and Python 3.11 or newer are required. The Docker variant is described in the README.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent runs SQL++ queries with the database user's rights and, with writes enabled, can change and delete documents
- The product sends usage data to Couchbase
This is third-party code. Review the repository files before installing.
What it does
Couchbase is a document database that runs in the Capella cloud or on your own cluster. The server connects an agent to it and ships as a PyPI package and a Docker image with two run modes. The operational server (`operational`) opens a cluster: 52 tools for health checks, schemas, key-value document access, SQL++ queries, indexes, full-text and vector search and query performance analysis. The Operational Insights server (`operational-insights`) targets clusters running the Operational Insights product, which Capella lacks: it has 13 tools for schemas, synchronous and asynchronous SQL++ queries, indexes and exports. By default the server only reads: write tools are not loaded and data-changing queries are blocked until you set CB_MCP_READ_ONLY_MODE=false. Individual tools can be turned off with CB_MCP_DISABLED_TOOLS or put behind user confirmation. The stdio transport suits desktop clients, while Streamable HTTP supports OAuth 2.1, health checks and audit logging for shared deployments.
Who it is for. Couchbase developers and database administrators who explore schemas and slow queries through Claude Desktop, Cursor, Windsurf, VS Code or JetBrains.
Good fit when
- You need to learn which buckets, scopes and collections a cluster has and the schema of the orders collection
- You want the five slowest queries of the last hour and a check for a missing covering index
- You need a quick check of whether the cluster is healthy and which services run on it
- You want the ten most recent users documents with status active without hand-written SQL++
- The cluster is shared by a team and the server has to run over HTTP with OAuth and audit logging
Not a fit when
- The agent must change data under the default read mode: writes are enabled separately and open INSERT, UPDATE and DELETE
- You want the only security barrier inside MCP: tools merely guide the model, while the Couchbase user's RBAC sets the access boundary
- Your database is not Couchbase: the server uses the Couchbase Python SDK
Example request
Which buckets and collections does the cluster have, what is the schema of orders and which five queries were slowest in the last hour?MCP
- Transport
- stdio, http
- Authentication
- key is optional
Environment variables
CB_CONNECTION_STRINGrequired- Cluster connection string, couchbase:// or couchbases://
CB_USERNAME- User name for basic authentication
CB_PASSWORDsecret- Database user password
CB_MCP_READ_ONLY_MODE- The value false enables write tools
Limitations
You need a Couchbase cluster (the Capella free tier works) and credentials: a login with password or an mTLS client certificate. Running from PyPI needs uv and Python 3.11 or newer; running in Docker needs only Docker. The Operational Insights server takes the HTTP(S) address of an Operational Insights cluster and does not accept a couchbase:// connection string.
Disabling write tools does not stop `run_sql_plus_plus_query` from running INSERT, UPDATE, DELETE and MERGE if the database user has such rights: RBAC is the final boundary. The product sends usage data to Couchbase, and the LLM limitations section warns about possible inaccurate model output.
How to disable. Remove the couchbase block from the client configuration. Disable or delete the database user created for the agent in Couchbase and change the password.
FAQ
How do I connect Couchbase to Claude Desktop or Cursor?
Add a couchbase block under mcpServers with command uvx and args couchbase-mcp-server, operational, and pass CB_CONNECTION_STRING, CB_USERNAME and CB_PASSWORD in env. Instead of uvx you can run the couchbase/mcp-server:latest image through Docker.
Can the agent change data?
Not by default: read-only mode does not load write tools and blocks data-changing queries. To allow writes set CB_MCP_READ_ONLY_MODE=false, and better still limit the rights of the database user itself.
How do the two servers in the package differ?
The operational server works with any Couchbase cluster in Capella or self-managed, with 52 tools. The Operational Insights server targets clusters with the Operational Insights product, is unavailable on Capella and has 13 tools.
How do I secure a shared deployment?
Run the server over Streamable HTTP with OAuth 2.1 through any JWKS-publishing provider, for example Auth0, Okta, Keycloak, Entra or Cognito. Turn on audit logging and health checks and give the database user minimal rights.
Can sensitive tools require confirmation?
Yes, sensitive tools can be put behind user confirmation and unneeded ones turned off with CB_MCP_DISABLED_TOOLS. This guides the model and does not replace RBAC.
Discussion
No questions or reviews yet.
Related
MCP serversOfficial MongoDB MCP server: queries and aggregations, index management, Atlas clusters and local deployments
One MCP server for SQLite, SQL Server, PostgreSQL and MySQL: read and change data, edit schemas and export to CSV and JSON
Elasticsearch MCP connects multiple search clusters, with an explicit target name and access scoped to the supplied credentials.
Official ClickHouse MCP server: the agent lists databases and tables and runs SQL, read-only by default
Official MCP server from the OpenSearch project exposes a cluster to agents: indexes, mappings, DSL search and shard state.
MCP MongoDB Server (kiliczsh)
MCP MongoDB Server
An MCP server that gives an agent queries, aggregations and writes in MongoDB and starts with one npx command, no install
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Couchbase MCP Server (this card) | yes | key is optional | 34 | |
| MongoDB MCP Server | yes | key is optional | 1,161 | MongoDB, a different document database |
| Redis MCP Server | yes | not required | 642 | the Redis key-value store |
| ClickHouse MCP Server | no | API key | 904 | a columnar analytics database without a document model |
README in short
The README covers choosing between the two servers, quick start through uvx and Docker, password and mTLS sign-in, tool tables, embedding providers, safety controls, transports, OAuth 2.1, logging and auditing, client setup and troubleshooting.