Couchbase

-

Inspect cluster health— Ask your assistant to check cluster status and running services viaget_cluster_health_and_services, or pull cached diagnostics withget_cluster_diagnostics_report.

Explore data schema— Discover buckets, scopes, and collections usingget_buckets_in_clusterandget_scopes_and_collections_in_bucket, then inspect a collection's structure withget_schema_for_collection.

Read and modify documents— Retrieve documents by ID withget_document_by_id, or fetch only specific fields vialookup_subdocument; write operations likeupsert_document_by_idare available when not in read-only mode.

Run and analyze SQL++ queries— Execute queries scoped to a bucket/scope withrun_sql_plus_plus_query, or generate an EXPLAIN plan and evaluation viaexplain_sql_plus_plus_query.

Optimize query performance— List indexes withlist_indexes, get recommendations fromget_index_advisor_recommendations, and identify slow or non-selective queries using tools likeget_longest_running_queriesandget_queries_not_selective.

Couchbase MCP Server is a self-hosted MCP Server that allows AI agents to connect to and interact with data in Couchbase clusters, whether hosted on Capella or self-managed. It provides tools across categories including Cluster Health, Data Schema, Key-Value, Query, and Performance — with safety controls via read-only mode and fine-grained tool disabling. It supports both STDIO and Streamable HTTP transports.

Couchbase MCP server is distributed as a Python Package Index (PyPI) package and via Docker. Enterprise support for Couchbase MCP Server is available by licensingCouchbase AI Data Plane, which also entitles use and enterprise support of Couchbase Agent Memory and Couchbase Agent Catalog.

For full documentation, visitmcp-server.couchbase.com.

- Python 3.10 or higher.
- A running Couchbase cluster. The easiest way to get started is to useCapellafree tier, which is fully managed version of Couchbase server. You can followinstructionsto import one of the sample datasets or import your own.
- uvinstalled to run the server.
- AnMCP clientsuch asClaude Desktopinstalled to connect the server to Claude. The instructions are provided for Claude Desktop and Cursor. Other MCP clients could be used as well.

We publish a pre builtPyPI packagefor the MCP server.

{ "mcpServers": { "couchbase": { "command": "uvx", "args": ["couchbase-mcp-server"], "env": { "CB_CONNECTION_STRING": "couchbases://connection-string", "CB_USERNAME": "username", "CB_PASSWORD": "password" } } } }

{ "mcpServers": { "couchbase": { "command": "uvx", "args": ["couchbase-mcp-server"], "env": { "CB_CONNECTION_STRING": "couchbases://connection-string", "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem", "CB_CLIENT_KEY_PATH": "/path/to/client.key" } } } }

Note: If you have other MCP servers in use in the client, you can add it to the existingmcpServersobject.

The MCP server can be run from the source using this repository.

Clone the repository to your local machine

git clone https://github.com/couchbase/mcp-server-couchbase.git

Server Configuration using Source for MCP Clients

This is the common configuration for the MCP clients such as Claude Desktop, Cursor, Windsurf Editor.

{ "mcpServers": { "couchbase": { "command": "uv", "args": [ "--directory", "path/to/cloned/repo/mcp-server-couchbase/", "run", "src/mcp_server.py" ], "env": { "CB_CONNECTION_STRING": "couchbases://connection-string", "CB_USERNAME": "username", "CB_PASSWORD": "password" } } } }

Note:path/to/cloned/repo/mcp-server-couchbase/should be the path to the cloned repository on your local machine. Don't forget the trailing slash at the end!

Note: If you have other MCP servers in use in the client, you can add it to the existingmcpServersobject.

The server can be configured using environment variables or command line arguments:

CB_MCP_READ_ONLY_MODEis the single switch controlling write operations:

- Whentrue(default): All write operations (KV, Query, scope/collection management, and index management) are disabled. KV write tools (upsert, insert, replace, delete, sub-document mutate), scope/collection management write tools (create_scope, create_collection, delete_scope, delete_collection), and index write tools (create_index, build_index, drop_index) arenot loadedand will not be available to the LLM, and SQL++ queries that modify data or structure are blocked.
- Whenfalse: KV, scope/collection management, and index write tools are loaded and SQL++ data/structure modification queries are allowed.

This is the recommended safe default to prevent inadvertent data modifications by LLMs.

Note: For authentication, you need either the Username and Password or the Client Certificate and key paths. Optionally, you can specify the CA root certificate path that will be used to validate the server certificates. If both the Client Certificate & key path and the username and password are specified, the client certificates will be used for authentication.

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.

# 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

# 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):

# 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.

{ "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):

{ "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" } } } }

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 disableupsert_document_by_idanddelete_document_by_id, data modifications can still occur via therun_sql_plus_plus_querytool using SQL++ DML statements (INSERT, UPDATE, DELETE, MERGE) unless:

- TheCB_MCP_READ_ONLY_MODEis set totrue(default), 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 tool disabling as an additional layer to guide LLM behavior and reduce the attack surface, not as the sole security control.

You can require explicit user confirmation for specific tools before execution (when the MCP client supports elicitation).

CB_MCP_CONFIRMATION_REQUIRED_TOOLS/--confirmation-required-toolssupports these formats:

- Comma-separated list
- File path (one tool name per line,#comments supported)

# Environment variable CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id" # Command line uvx couchbase-mcp-server --confirmation-required-tools delete_document_by_id,replace_document_by_id

- If the client supports elicitation, the user is prompted to confirm.
- If the client does not support elicitation, the tool executes without confirmation for backward compatibility.

You can also check the version of the server using:

The MCP server logs tostderrby default. Logging is configured with theCB_MCP_LOG_*variables listed inAdditional Configuration:

# Enable debug logging to both stderr and rotating per-level files uvx couchbase-mcp-server --log-level=debug --log-sinks=stderr,file # Keep 30 rotated ERROR backups but only the live DEBUG file uvx couchbase-mcp-server --log-level=debug --log-sinks=file \ --log-error-retention-backup-count=30 --log-debug-retention-backup-count=0

For more details, see thedocumentation.

The MCP server can now be added to Claude Desktop by editing the configuration file. More detailed instructions can be found on theMCP quickstart guide.

Open the configuration file and add theconfigurationto themcpServerssection.

The logs can be used to diagnose connection issues or other problems with your MCP server configuration. For more details, refer to theofficial documentation.

In Cursor, go to Cursor > Cursor Settings > Tools & Integrations > MCP Tools. Also, checkout the docs onsetting up MCP server configurationfrom Cursor.

Specify the sameconfigurationmanually, or use the one-clickInstall in Cursorlink. You may need to add the server configuration under a parent key ofmcpServers.

For more details about MCP integration with Cursor, refer to theofficial Cursor MCP documentation.

Follow the steps below to use the Couchbase MCP server withWindsurf Editor.
-

InstallWindsurf Editoron your machine.

In Windsurf Editor, navigate to Command Palette > Windsurf MCP Configuration Panel or Windsurf - Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers. For more details on the configuration, please refer to theofficial documentation.

Click on Add Server and then Add custom server. On the configuration that opens in the editor, add the Couchbase MCP Serverconfigurationfrom above.

For more details about MCP integration with Windsurf Editor, refer to the officialWindsurf MCP documentation.

Follow the steps below to use the Couchbase MCP server withVS Code.

- Create a new file in workspace as .vscode/mcp.json.
- Add theconfigurationand save the file.

- RunMCP: Open User Configurationin the Command Palette (Ctrl+Shift+PorCmd+Shift+P)
- Add theconfigurationand save the file.