# Couchbase MCP Server
Pre-built images for the [Couchbase](https://www.couchbase.com/) MCP Server.
A Model Context Protocol (MCP) server that allows AI agents to interact with Couchbase databases.
Github Repo: https://github.com/Couchbase-Ecosystem/mcp-server-couchbase
Dockerfile: https://github.com/Couchbase-Ecosystem/mcp-server-couchbase/blob/main/Dockerfile
## Features/Tools
### Cluster setup & health tools
| Tool Name | Description |
|-----------|-------------|
| `get_server_configuration_status` | Get the status of the MCP server |
| `test_cluster_connection` | Check the cluster credentials by connecting to the cluster |
| `get_cluster_health_and_services` | Get cluster health status and list of all running services |
### Data model & schema discovery tools
| Tool Name | Description |
|-----------|-------------|
| `get_buckets_in_cluster` | Get a list of all the buckets in the cluster |
| `get_scopes_in_bucket` | Get a list of all the scopes in the specified bucket |
| `get_collections_in_scope` | Get a list of all the collections in a specified scope and bucket. Note that this tool requires the cluster to have Query service. |
| `get_scopes_and_collections_in_bucket` | Get a list of all the scopes and collections in the specified bucket |
| `get_schema_for_collection` | Get the structure for a collection |
### Document KV operations tools
| Tool Name | Description |
|-----------|-------------|
| `get_document_by_id` | Get a document by ID from a specified scope and collection |
| `upsert_document_by_id` | Upsert a document by ID to a specified scope and collection. **Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.** |
| `insert_document_by_id` | Insert a new document by ID (fails if document exists). **Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.** |
| `replace_document_by_id` | Replace an existing document by ID (fails if document doesn't exist). **Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.** |
| `delete_document_by_id` | Delete a document by ID from a specified scope and collection. **Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.** |
### Query and indexing tools
| Tool Name | Description |
|-----------|-------------|
| `list_indexes` | List all indexes in the cluster with their definitions, with optional filtering by bucket, scope, collection and index name. |
| `get_index_advisor_recommendations` | Get index recommendations from Couchbase Index Advisor for a given SQL++ query to optimize query performance |
| `run_sql_plus_plus_query` | Run a [SQL++ query](https://www.couchbase.com/sqlplusplus/) on a specified scope.<br><br>Queries are automatically scoped to the specified bucket and scope, so use collection names directly (e.g., `SELECT * FROM users` instead of `SELECT * FROM bucket.scope.users`).<br><br>`CB_MCP_READ_ONLY_MODE` is `true` by default, which means that **all write operations (KV and Query)** are disabled. When enabled, KV write tools are not loaded and SQL++ queries that modify data are blocked. |
### Query performance analysis tools
| Tool Name | Description |
|-----------|-------------|
| `get_longest_running_queries` | Get longest running queries by average service time |
| `get_most_frequent_queries` | Get most frequently executed queries |
| `get_queries_with_largest_response_sizes` | Get queries with the largest response sizes |
| `get_queries_with_large_result_count` | Get queries with the largest result counts |
| `get_queries_using_primary_index` | Get queries that use a primary index (potential performance concern) |
| `get_queries_not_using_covering_index` | Get queries that don't use a covering index |
| `get_queries_not_selective` | Get queries that are not selective (index scans return many more documents than final result) |
## Usage
The Docker images can be used in the supported MCP clients such as Claude Desktop, Cursor, Windsurf, etc in combination with Docker.
### Configuration
Add the configuration specified below to the MCP configuration in your MCP client.
- Claude Desktop: https://modelcontextprotocol.io/quickstart/user
- Cursor: https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers
- Windsurf: https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin
```json
{
"mcpServers": {
"couchbase": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"CB_CONNECTION_STRING=<couchbase_connection_string>",
"-e",
"CB_USERNAME=<database_username>",
"-e",
"CB_PASSWORD=<database_password>",
"couchbaseecosystem/mcp-server-couchbase:latest"
]
}
}
}
```
### Environment Variables
The detailed explanation for the environment variables can be found on the [Github Repo](https://github.com/Couchbase-Ecosystem/mcp-server-couchbase?tab=readme-ov-file#additional-configuration-for-mcp-server).
| Variable | Description | Default |
| ----------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `CB_CONNECTION_STRING` | Couchbase Connection string | **Required** |
| `CB_USERNAME` | Database username | **Required (or Client Certificate and Key needed for mTLS)** |
| `CB_PASSWORD` | Database password | **Required (or Client Certificate and Key needed for mTLS)** |
| `CB_CLIENT_CERT_PATH` | Path to the client certificate file for mTLS authentication | **Required if using mTLS (or Username and Password required)** |
| `CB_CLIENT_KEY_PATH` | Path to the client key file for mTLS authentication | **Required if using mTLS (or Username and Password required)** |
| `CB_CA_CERT_PATH` | Path to server root certificate for TLS if server is configured with a self-signed/untrusted certificate. | |
| `CB_MCP_READ_ONLY_MODE` | Prevent all data modifications (KV and Query). When `true`, KV write tools are not loaded. | `true` |
| `CB_MCP_TRANSPORT` | Transport mode (stdio/http/sse) | `stdio` |
| `CB_MCP_HOST` | Server host (HTTP/SSE modes) | `127.0.0.1` |
| `CB_MCP_PORT` | Server port (HTTP/SSE modes) | `8000` |
| `CB_MCP_DISABLED_TOOLS` | Tools to disable | |
### Disabling Tools
You can disable specific tools to prevent them from being loaded and exposed to the MCP client. Disabled tools will not appear in the tool discovery and cannot be invoked by the LLM.
#### Supported Formats
**Comma-separated list:**
```bash
# Environment variable
CB_MCP_DISABLED_TOOLS="upsert_document_by_id, delete_document_by_id"
# Command line
uvx couchbase-mcp-server --disabled-tools upsert_document_by_id, delete_document_by_id
```
**File path (one tool name per line):**
```bash
# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt
# Command line
uvx couchbase-mcp-server --disabled-tools disabled_tools.txt
```
**File format (e.g., `disabled_tools.txt`):**
```text
# Write operations
upsert_document_by_id
delete_document_by_id
# Index advisor
get_index_advisor_recommendations
```
Lines starting with `#` are treated as comments and ignored.
#### MCP Client Configuration Examples
**Using comma-separated list:**
```json
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password",
"CB_MCP_DISABLED_TOOLS": "upsert_document_by_id,delete_document_by_id"
}
}
}
}
```
**Using file path (recommended for many tools):**
```json
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password",
"CB_MCP_DISABLED_TOOLS": "/path/to/disabled_tools.txt"
}
}
}
}
```
#### Important Security Note
> **Warning:** Disabling tools alone does not guarantee that certain operations cannot be performed. The underlying database user's RBAC (Role-Based Access Control) permissions are the authoritative security control.
>
> For example, even if you disable `upsert_document_by_id` and `delete_document_by_id`, data modifications can still occur via the `run_sql_plus_plus_query` tool using SQL++ DML statements (INSERT, UPDATE, DELETE, MERGE) unless:
> - The `CB_MCP_READ_ONLY_MODE` is set to `true` (default), which disables all write operations (KV and Query), OR
> - The database user lacks the necessary RBAC permissions for data modification
>
> **Best Practice:** Always configure appropriate RBAC permissions on your Couchbase user credentials as the primary security measure. Use `CB_MCP_READ_ONLY_MODE=true` (the default) for comprehensive write protection, and tool disabling as an additional layer to guide LLM behavior.
