Couchbase MCP Server – Cluster Data Access
Couchbase MCP Server is an official Couchbase-maintained Model Context Protocol server for interacting with Couchbase clusters, including Capella and self-managed deployments. It gives MCP clients controlled access to cluster health, buckets, scopes, collections, schemas, SQL++ queries, index information, and document key-value operations.
Overview
Couchbase MCP Server connects MCP-aware AI clients to Couchbase clusters so an agent can inspect data models, run SQL++ queries, and work with documents through a documented set of tools. The server is maintained in the official Couchbase GitHub organization and is described by Couchbase as an open-source, community-supported offering for agentic workflows against Couchbase Capella or self-managed Couchbase Server clusters.
What the MCP server enables
The server exposes tools for cluster setup and health checks, data model discovery, key-value document operations, SQL++ querying, index inspection, and index-advisor recommendations. Examples include checking server configuration, testing cluster connectivity, listing buckets, scopes, and collections, inspecting collection schemas, retrieving documents by ID, running SQL++ queries, listing indexes, and requesting index-advisor recommendations.
Document modification tools such as insert, upsert, replace, and delete are available, but they are disabled by default when CB_MCP_READ_ONLY_MODE=true. Couchbase also documents tool-disabling and confirmation-required settings so teams can reduce the exposed tool surface or require user confirmation where supported by the MCP client.
When to use it
Use this MCP server when an AI assistant needs live Couchbase context instead of relying on static knowledge. Practical workflows include asking an IDE assistant to inspect a Capella sample bucket, explain a collection schema, draft or test SQL++ queries, retrieve a document by ID during debugging, or recommend indexes for a query. It is also useful for exploratory data access in agentic applications where the model needs structured tool calls against Couchbase rather than free-form database instructions.
Connection and authentication
The server can run locally through the PyPI package with uvx couchbase-mcp-server, from source with uv, or in Docker. Standard stdio configuration uses CB_CONNECTION_STRING, CB_USERNAME, and CB_PASSWORD. The repository also documents mTLS credentials through CB_CLIENT_CERT_PATH and CB_CLIENT_KEY_PATH. Streamable HTTP mode is available at the local /mcp endpoint, and SSE mode is still available at /sse but is documented as deprecated in favor of Streamable HTTP.
Key considerations
Couchbase notes that Streamable HTTP mode does not include authorization support, so it should be bound and exposed carefully. Database RBAC remains the authoritative control: disabling MCP tools alone is not sufficient to prevent writes if the underlying Couchbase user can still perform SQL++ data modification. For production use, create least-privilege Couchbase credentials, keep read-only mode enabled unless writes are required, restrict network access to local HTTP/SSE endpoints, and require confirmation for risky tools when the MCP client supports elicitation.
Supported Transports
stdio
Command: uvx
Args:
couchbase-mcp-server
streamable_http
URL: http://localhost:8000/mcp
sse
URL: http://localhost:8000/sse
Frequently Asked Questions
- When should an AI agent use the Couchbase MCP Server?
- Use it when an agent needs live access to a Couchbase Capella or self-managed Couchbase Server cluster for schema discovery, query assistance, document inspection, cluster health checks, or index-advisor workflows.
- What does Couchbase MCP Server add to an AI agent's capabilities?
- It adds structured tools for Couchbase-specific work, including testing cluster connectivity, listing buckets, scopes, and collections, reading collection schemas, retrieving documents, running SQL++ queries, listing indexes, and requesting index recommendations.
- Can the server modify Couchbase data?
- Yes, the server includes document operations such as insert, upsert, replace, and delete, but these write tools are disabled by default when `CB_MCP_READ_ONLY_MODE=true`. Couchbase recommends using database RBAC as the primary security control.
- How is authentication configured for Couchbase MCP Server?
- Standard configuration uses a Couchbase connection string with `CB_CONNECTION_STRING`, `CB_USERNAME`, and `CB_PASSWORD`. The documented mTLS option uses `CB_CLIENT_CERT_PATH` and `CB_CLIENT_KEY_PATH` instead of username and password credentials.
- Which transport should be used for Couchbase MCP Server?
- Use stdio for local desktop and IDE clients through `uvx couchbase-mcp-server`. Use Streamable HTTP at `http://localhost:8000/mcp` when multiple clients need to connect to a shared local server. SSE at `http://localhost:8000/sse` is supported but documented as deprecated in favor of Streamable HTTP.