# Mcp Server Couchbase > Couchbase Model Context Protocol Server to interact with Couchbase clusters - **Type:** MCP server - **Install:** `agentstack add mcp-couchbase-ecosystem-mcp-server-couchbase` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [couchbase](https://agentstack.voostack.com/s/couchbase) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.5.2 - **License:** Apache-2.0 - **Upstream author:** [couchbase](https://github.com/couchbase) - **Source:** https://github.com/couchbase/mcp-server-couchbase - **Website:** https://mcp-server.couchbase.com/ ## Install ```sh agentstack add mcp-couchbase-ecosystem-mcp-server-couchbase ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Couchbase MCP Server An [MCP](https://modelcontextprotocol.io/) server implementation of Couchbase that allows LLMs to directly interact with Couchbase clusters. [](https://mcp-server.couchbase.com/) [](https://opensource.org/licenses/Apache-2.0) [](https://www.python.org/downloads/) [](https://pypi.org/project/couchbase-mcp-server/) [][cursor-install-basic] [](https://mseep.ai/app/13fce476-0e74-4b1e-ab82-1df2a3204809) [](https://archestra.ai/mcp-catalog/couchbase-ecosystem__mcp-server-couchbase) For full documentation, visit [mcp-server.couchbase.com](https://mcp-server.couchbase.com/). ## 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. Set `return_raw_index_stats=true` to return the unprocessed index information. | | `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.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`).`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. | | `explain_sql_plus_plus_query` | Generate and evaluate an EXPLAIN plan for a SQL++ query. Returns query metadata, extracted plan, and plan evaluation findings. | ### 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) | ## Prerequisites - Python 3.10 or higher. - A running Couchbase cluster. The easiest way to get started is to use [Capella](https://docs.couchbase.com/cloud/get-started/create-account.html#getting-started) free tier, which is fully managed version of Couchbase server. You can follow [instructions](https://docs.couchbase.com/cloud/clusters/data-service/import-data-documents.html#import-sample-data) to import one of the sample datasets or import your own. - [uv](https://docs.astral.sh/uv/) installed to run the server. - An [MCP client](https://modelcontextprotocol.io/clients) such as [Claude Desktop](https://claude.ai/download) installed to connect the server to Claude. The instructions are provided for Claude Desktop and Cursor. Other MCP clients could be used as well. ## Configuration The MCP server can be run either from the prebuilt PyPI package or the source using uv. ### Running from PyPI We publish a pre built [PyPI package](https://pypi.org/project/couchbase-mcp-server/) for the MCP server. #### Server Configuration using Pre built Package for MCP Clients #### Basic Authentication ```json { "mcpServers": { "couchbase": { "command": "uvx", "args": ["couchbase-mcp-server"], "env": { "CB_CONNECTION_STRING": "couchbases://connection-string", "CB_USERNAME": "username", "CB_PASSWORD": "password" } } } } ``` or #### mTLS ```json { "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 existing `mcpServers` object. ### Running from Source The MCP server can be run from the source using this repository. #### Clone the repository to your local machine ```bash 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. ```json { "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 existing `mcpServers` object. ### Additional Configuration for MCP Server The server can be configured using environment variables or command line arguments: | Environment Variable | CLI Argument | Description | Default | | ---------------------------- | ------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------- | | `CB_CONNECTION_STRING` | `--connection-string` | Connection string to the Couchbase cluster | **Required** | | `CB_USERNAME` | `--username` | Username with access to required buckets for basic authentication | **Required (or Client Certificate and Key needed for mTLS)** | | `CB_PASSWORD` | `--password` | Password for basic authentication | **Required (or Client Certificate and Key needed for mTLS)** | | `CB_CLIENT_CERT_PATH` | `--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` | `--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` | `--ca-cert-path` | Path to server root certificate for TLS if server is configured with a self-signed/untrusted certificate. This will not be required if you are connecting to Capella | | | `CB_MCP_READ_ONLY_MODE` | `--read-only-mode` | Prevent all data modifications (KV and Query). When enabled, KV write tools are not loaded. | `true` | | `CB_MCP_TRANSPORT` | `--transport` | Transport mode: `stdio`, `http`, `sse` | `stdio` | | `CB_MCP_HOST` | `--host` | Host for HTTP/SSE transport modes | `127.0.0.1` | | `CB_MCP_PORT` | `--port` | Port for HTTP/SSE transport modes | `8000` | | `CB_MCP_DISABLED_TOOLS` | `--disabled-tools` | Tools to disable (see [Disabling Tools](#disabling-tools)) | None | | `CB_MCP_CONFIRMATION_REQUIRED_TOOLS` | `--confirmation-required-tools` | Tools that require explicit user confirmation before execution via MCP elicitation (see [Elicitation/Confirmation Required Tools](#elicitationconfirmation-for-tool-calls)) | None | #### Read-Only Mode Configuration **`CB_MCP_READ_ONLY_MODE`** is the single switch controlling write operations: - When `true` (default): All write operations (KV and Query) are disabled. KV write tools (upsert, insert, replace, delete) are **not loaded** and will not be available to the LLM, and SQL++ queries that modify data or structure are blocked. - When `false`: KV 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. ### 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), 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. ### Elicitation/Confirmation for Tool Calls You can require explicit user confirmation for specific tools before execution (when the MCP client supports elicitation). `CB_MCP_CONFIRMATION_REQUIRED_TOOLS` / `--confirmation-required-tools` supports these formats: - Comma-separated list - File path (one tool name per line, `#` comments supported) **Example:** ```bash # 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 ``` When a listed tool is invoked: - 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: ```bash uvx couchbase-mcp-server --version ``` ### Client Specific Configuration Claude Desktop Follow the steps below to use Couchbase MCP server with Claude Desktop MCP client 1. The MCP server can now be added to Claude Desktop by editing the configuration file. More detailed instructions can be found on the [MCP quickstart guide](https://modelcontextprotocol.io/quickstart/user). - On Mac, the configuration file is located at `~/Library/Application Support/Claude/claude_desktop_config.json` - On Windows, the configuration file is located at `%APPDATA%\Claude\claude_desktop_config.json` Open the configuration file and add the [configuration](#configuration) to the `mcpServers` section. 2. Restart Claude Desktop to apply the changes. 3. You can now use the server in Claude Desktop to run queries on the Couchbase cluster using natural language and perform CRUD operations on documents. Logs The logs for Claude Desktop can be found in the following locations: - MacOS: ~/Library/Logs/Claude - Windows: %APPDATA%\Claude\Logs The logs can be used to diagnose connection issues or other problems with your MCP server configuration. For more details, refer to the [official documentation](https://modelcontextprotocol.io/quickstart/user#troubleshooting). Cursor Follow steps below to use Couchbase MCP server with Cursor: 1. Install [Cursor](https://cursor.sh/) on your machine. 2. In Cursor, go to Cursor > Cursor Settings > Tools & Integrations > MCP Tools. Also, checkout the docs on [setting up MCP server configuration](https://docs.cursor.com/en/context/mcp#configuring-mcp-servers) from Cursor. 3. Specify the same [configuration](#configuration) manually, or use the one-click [Install in Cursor][cursor-install-basic] link. You may need to add the server configuration under a parent key of `mcpServers`. > Note: The install link uses placeholder values from the configuration examples above. Update the connection string and credentials after installation. 4. Save the configuration. 5. You will see couchbase as an added server in MCP servers list. Refresh to see if server is enabled. 6. You can now use the Couchbase MCP server in Cursor to query your Couchbase cluster using natural language and perform CRUD operations on documents. [cursor-install-basic]: htt … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [couchbase](https://github.com/couchbase) - **Source:** [couchbase/mcp-server-couchbase](https://github.com/couchbase/mcp-server-couchbase) - **License:** Apache-2.0 - **Homepage:** https://mcp-server.couchbase.com/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.5.2 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.5.2** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-couchbase-ecosystem-mcp-server-couchbase - Seller: https://agentstack.voostack.com/s/couchbase - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.