An MCP server implementation of Couchbase that allows LLMs to directly interact with Couchbase clusters. - Python 3.10 or higher. - A running Couchbase cluster. The easiest way to get started is to use Capella free tier, which is fully managed version of Couchbase server. You can follow instructions to import one of the sample datasets or import your own. - uv installed to run the server. - An MCP
Add this skill
npx mdskills install Couchbase-Ecosystem/mcp-server-couchbaseComprehensive Couchbase database toolkit with extensive tools and strong security defaults
1# Couchbase MCP Server23An [MCP](https://modelcontextprotocol.io/) server implementation of Couchbase that allows LLMs to directly interact with Couchbase clusters.45[](https://opensource.org/licenses/Apache-2.0) [](https://www.python.org/downloads/) [](https://pypi.org/project/couchbase-mcp-server/) [](https://mseep.ai/app/13fce476-0e74-4b1e-ab82-1df2a3204809) [](https://archestra.ai/mcp-catalog/couchbase-ecosystem__mcp-server-couchbase)67<a href="https://glama.ai/mcp/servers/@Couchbase-Ecosystem/mcp-server-couchbase">8 <img width="380" height="200" src="https://glama.ai/mcp/servers/@Couchbase-Ecosystem/mcp-server-couchbase/badge" alt="Couchbase Server MCP server" />9</a>1011<!-- mcp-name: io.github.Couchbase-Ecosystem/mcp-server-couchbase -->1213## Features/Tools14### Cluster setup & health tools15| Tool Name | Description |16|-----------|-------------|17| `get_server_configuration_status` | Get the status of the MCP server |18| `test_cluster_connection` | Check the cluster credentials by connecting to the cluster |19| `get_cluster_health_and_services` | Get cluster health status and list of all running services |2021### Data model & schema discovery tools22| Tool Name | Description |23|-----------|-------------|24| `get_buckets_in_cluster` | Get a list of all the buckets in the cluster |25| `get_scopes_in_bucket` | Get a list of all the scopes in the specified bucket |26| `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. |27| `get_scopes_and_collections_in_bucket` | Get a list of all the scopes and collections in the specified bucket |28| `get_schema_for_collection` | Get the structure for a collection |2930### Document KV operations tools31| Tool Name | Description |32|-----------|-------------|33| `get_document_by_id` | Get a document by ID from a specified scope and collection |34| `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`.** |35| `insert_document_by_id` | Insert a new document by ID (fails if document exists). **Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.** |36| `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`.** |37| `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`.** |3839### Query and indexing tools40| Tool Name | Description |41|-----------|-------------|42| `list_indexes` | List all indexes in the cluster with their definitions, with optional filtering by bucket, scope, collection and index name. |43| `get_index_advisor_recommendations` | Get index recommendations from Couchbase Index Advisor for a given SQL++ query to optimize query performance |44| `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. |4546### Query performance analysis tools47| Tool Name | Description |48|-----------|-------------|49| `get_longest_running_queries` | Get longest running queries by average service time |50| `get_most_frequent_queries` | Get most frequently executed queries |51| `get_queries_with_largest_response_sizes` | Get queries with the largest response sizes |52| `get_queries_with_large_result_count` | Get queries with the largest result counts |53| `get_queries_using_primary_index` | Get queries that use a primary index (potential performance concern) |54| `get_queries_not_using_covering_index` | Get queries that don't use a covering index |55| `get_queries_not_selective` | Get queries that are not selective (index scans return many more documents than final result) |5657## Prerequisites5859- Python 3.10 or higher.60- 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.61- [uv](https://docs.astral.sh/uv/) installed to run the server.62- 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.6364## Configuration6566The MCP server can be run either from the prebuilt PyPI package or the source using uv.6768### Running from PyPI6970We publish a pre built [PyPI package](https://pypi.org/project/couchbase-mcp-server/) for the MCP server.7172#### Server Configuration using Pre built Package for MCP Clients7374#### Basic Authentication7576```json77{78 "mcpServers": {79 "couchbase": {80 "command": "uvx",81 "args": ["couchbase-mcp-server"],82 "env": {83 "CB_CONNECTION_STRING": "couchbases://connection-string",84 "CB_USERNAME": "username",85 "CB_PASSWORD": "password"86 }87 }88 }89}90```9192or9394#### mTLS9596```json97{98 "mcpServers": {99 "couchbase": {100 "command": "uvx",101 "args": ["couchbase-mcp-server"],102 "env": {103 "CB_CONNECTION_STRING": "couchbases://connection-string",104 "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",105 "CB_CLIENT_KEY_PATH": "/path/to/client.key"106 }107 }108 }109}110```111112> Note: If you have other MCP servers in use in the client, you can add it to the existing `mcpServers` object.113114### Running from Source115116The MCP server can be run from the source using this repository.117118#### Clone the repository to your local machine.119120```bash121git clone https://github.com/Couchbase-Ecosystem/mcp-server-couchbase.git122```123124#### Server Configuration using Source for MCP Clients125126This is the common configuration for the MCP clients such as Claude Desktop, Cursor, Windsurf Editor.127128```json129{130 "mcpServers": {131 "couchbase": {132 "command": "uv",133 "args": [134 "--directory",135 "path/to/cloned/repo/mcp-server-couchbase/",136 "run",137 "src/mcp_server.py"138 ],139 "env": {140 "CB_CONNECTION_STRING": "couchbases://connection-string",141 "CB_USERNAME": "username",142 "CB_PASSWORD": "password"143 }144 }145 }146}147```148149> 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!150151> Note: If you have other MCP servers in use in the client, you can add it to the existing `mcpServers` object.152153### Additional Configuration for MCP Server154155The server can be configured using environment variables or command line arguments:156| Environment Variable | CLI Argument | Description | Default |157|--------------------------------|--------------------------|---------------------------------------------------------------------------------------------|------------------------------------------|158| `CB_CONNECTION_STRING` | `--connection-string` | Connection string to the Couchbase cluster | **Required** |159| `CB_USERNAME` | `--username` | Username with access to required buckets for basic authentication | **Required (or Client Certificate and Key needed for mTLS)** |160| `CB_PASSWORD` | `--password` | Password for basic authentication | **Required (or Client Certificate and Key needed for mTLS)** |161| `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)** |162| `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)** |163| `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 | |164| `CB_MCP_READ_ONLY_MODE` | `--read-only-mode` | Prevent all data modifications (KV and Query). When enabled, KV write tools are not loaded. | `true` |165| `CB_MCP_READ_ONLY_QUERY_MODE` | `--read-only-query-mode` | **[DEPRECATED]** Prevent queries that modify data. Note that data modification would still be possible via document operations tools. Use `CB_MCP_READ_ONLY_MODE` instead. | `true` |166| `CB_MCP_TRANSPORT` | `--transport` | Transport mode: `stdio`, `http`, `sse` | `stdio` |167| `CB_MCP_HOST` | `--host` | Host for HTTP/SSE transport modes | `127.0.0.1` |168| `CB_MCP_PORT` | `--port` | Port for HTTP/SSE transport modes | `8000` |169| `CB_MCP_DISABLED_TOOLS` | `--disabled-tools` | Tools to disable (see [Disabling Tools](#disabling-tools)) | None |170171#### Read-Only Mode Configuration172173The MCP server provides two configuration options for controlling write operations:174175**`CB_MCP_READ_ONLY_MODE`** (Recommended)176- When `true` (default): All write operations are disabled. KV write tools (upsert, insert, replace, delete) are **not loaded** and will not be available to the LLM.177- When `false`: KV write tools are loaded and available.178179**`CB_MCP_READ_ONLY_QUERY_MODE`** (Deprecated)180- This option only controls SQL++ query-based writes but does not prevent KV write operations.181- **Deprecated**: Use `CB_MCP_READ_ONLY_MODE` instead for comprehensive protection.182183**Mode Behavior Truth Table:**184185| `READ_ONLY_MODE` | `READ_ONLY_QUERY_MODE` | Result |186|------------------|------------------------|--------|187| `true` | `true` | Read-only KV and Query operations. All writes disabled. |188| `true` | `false` | Read-only KV and Query operations. All writes disabled. |189| `false` | `true` | Only Query writes disabled. KV writes allowed. |190| `false` | `false` | All KV and Query operations allowed. |191192> **Important**: When `READ_ONLY_MODE` is `true`, it takes precedence and disables all write operations regardless of `READ_ONLY_QUERY_MODE` setting. This is the recommended safe default to prevent inadvertent data modifications by LLMs.193194> 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.195> If both the Client Certificate & key path and the username and password are specified, the client certificates will be used for authentication.196197### Disabling Tools198199You 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.200201#### Supported Formats202203**Comma-separated list:**204205```bash206# Environment variable207CB_MCP_DISABLED_TOOLS="upsert_document_by_id, delete_document_by_id"208209# Command line210uvx couchbase-mcp-server --disabled-tools upsert_document_by_id, delete_document_by_id211```212213**File path (one tool name per line):**214215```bash216# Environment variable217CB_MCP_DISABLED_TOOLS=disabled_tools.txt218219# Command line220uvx couchbase-mcp-server --disabled-tools disabled_tools.txt221```222223**File format (e.g., `disabled_tools.txt`):**224225```text226# Write operations227upsert_document_by_id228delete_document_by_id229230# Index advisor231get_index_advisor_recommendations232```233234Lines starting with `#` are treated as comments and ignored.235236#### MCP Client Configuration Examples237238**Using comma-separated list:**239240```json241{242 "mcpServers": {243 "couchbase": {244 "command": "uvx",245 "args": ["couchbase-mcp-server"],246 "env": {247 "CB_CONNECTION_STRING": "couchbases://connection-string",248 "CB_USERNAME": "username",249 "CB_PASSWORD": "password",250 "CB_MCP_DISABLED_TOOLS": "upsert_document_by_id,delete_document_by_id"251 }252 }253 }254}255```256257**Using file path (recommended for many tools):**258259```json260{261 "mcpServers": {262 "couchbase": {263 "command": "uvx",264 "args": ["couchbase-mcp-server"],265 "env": {266 "CB_CONNECTION_STRING": "couchbases://connection-string",267 "CB_USERNAME": "username",268 "CB_PASSWORD": "password",269 "CB_MCP_DISABLED_TOOLS": "/path/to/disabled_tools.txt"270 }271 }272 }273}274```275276#### Important Security Note277278> **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.279>280> 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:281> - The `CB_MCP_READ_ONLY_MODE` is set to `true` (default), OR282> - The database user lacks the necessary RBAC permissions for data modification283>284> **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.285286You can also check the version of the server using:287288```bash289uvx couchbase-mcp-server --version290```291292### Client Specific Configuration293294<details>295<summary>Claude Desktop</summary>296297Follow the steps below to use Couchbase MCP server with Claude Desktop MCP client2982991. 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).300301 - On Mac, the configuration file is located at `~/Library/Application Support/Claude/claude_desktop_config.json`302 - On Windows, the configuration file is located at `%APPDATA%\Claude\claude_desktop_config.json`303304 Open the configuration file and add the [configuration](#configuration) to the `mcpServers` section.3053062. Restart Claude Desktop to apply the changes.3073083. 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.309310Logs311312The logs for Claude Desktop can be found in the following locations:313314- MacOS: ~/Library/Logs/Claude315- Windows: %APPDATA%\Claude\Logs316317The 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).318319</details>320321<details>322<summary>Cursor</summary>323324Follow steps below to use Couchbase MCP server with Cursor:3253261. Install [Cursor](https://cursor.sh/) on your machine.3273282. 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.3293303. Specify the same [configuration](#configuration). You may need to add the server configuration under a parent key of mcpServers.3313324. Save the configuration.3333345. You will see couchbase as an added server in MCP servers list. Refresh to see if server is enabled.3353366. You can now use the Couchbase MCP server in Cursor to query your Couchbase cluster using natural language and perform CRUD operations on documents.337338For more details about MCP integration with Cursor, refer to the [official Cursor MCP documentation](https://docs.cursor.com/en/context/mcp).339340Logs341342In the bottom panel of Cursor, click on "Output" and select "Cursor MCP" from the dropdown menu to view server logs. This can help diagnose connection issues or other problems with your MCP server configuration.343344</details>345346<details>347<summary>Windsurf Editor</summary>348349Follow the steps below to use the Couchbase MCP server with [Windsurf Editor](https://windsurf.com/).3503511. Install [Windsurf Editor](https://windsurf.com/download) on your machine.3523532. 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 the [official documentation](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin).3543553. Click on Add Server and then Add custom server. On the configuration that opens in the editor, add the Couchbase MCP Server [configuration](#configuration) from above.3563574. Save the configuration.3583595. You will see couchbase as an added server in MCP Servers list under Advanced Settings. Refresh to see if server is enabled.3603616. You can now use the Couchbase MCP server in Windsurf Editor to query your Couchbase cluster using natural language and perform CRUD operations on documents.362363For more details about MCP integration with Windsurf Editor, refer to the official [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp).364365</details>366367<details>368<summary>VS Code</summary>369370Follow the steps below to use the Couchbase MCP server with [VS Code](https://code.visualstudio.com/).3711. Install [VS Code](https://code.visualstudio.com/)3722. Following are a couple of ways to configure the MCP server.373 * For a Workspace server configuration374 - Create a new file in workspace as .vscode/mcp.json.375 - Add the [configuration](#configuration) and save the file.376 * For the Global server configuration:377 - Run **MCP: Open User Configuration** in the Command Pallete(`Ctrl+Shift+P` or `Cmd+Shift+P`)378 - Add the [configuration](#configuration) and save the file.379 * **Note**: VS Code uses `servers` as the top-level JSON property in mcp.json files to define MCP (Model Context Protocol) servers, while Cursor uses `mcpServers` for the equivalent configuration. Check the [VS Code client configurations](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for any further changes or details. An example VS Code configuration is provided below.380 ```json381 {382 "servers": {383 "couchbase": {384 "command": "uvx",385 "args": ["couchbase-mcp-server"],386 "env": {387 "CB_CONNECTION_STRING": "couchbases://connection-string",388 "CB_USERNAME": "username",389 "CB_PASSWORD": "password"390 }391 }392 }393 }394 ```3953. Once you save the file, the server starts and a small action list appears with `Running|Stop|n Tools|More..`.3964. Click on the options from the option list to `Start`/`Stop`/manage the server.3975. You can now use the Couchbase MCP server in VS Code to query your Couchbase cluster using natural language and perform CRUD operations on documents.398399Logs:400In the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`),401- run **MCP: List Servers** command and pick the couchbase server402- choose “Show Output” to see its logs in the Output tab.403</details>404405<details>406<summary>JetBrains IDEs</summary>407408Follow the steps below to use the Couchbase MCP server with [JetBrains IDEs](https://www.jetbrains.com/)4091. Install any one of the [JetBrains IDEs](https://www.jetbrains.com/)4102. Install any one of the JetBrains plugins - [AI Assistant](https://www.jetbrains.com/help/ai-assistant/getting-started-with-ai-assistant.html) or [Junie](https://www.jetbrains.com/help/junie/get-started-with-junie.html)4113. Navigate to **Settings > Tools > AI Assistant or Junie > MCP Server**4124. Click "+" to add the Couchbase MCP [configuration](#configuration) and click Save.4135. You will see the Couchbase MCP server added to the list of servers. Once you click Apply, the Couchbase MCP server starts and on-hover of status, it shows all the tools available.4146. You can now use the Couchbase MCP server in JetBrains IDEs to query your Couchbase cluster using natural language and perform CRUD operations on documents.415416Logs:417The log file can be explored at **Help > Show Log in Finder (Explorer) > mcp > couchbase**418419</details>420421## Streamable HTTP Transport Mode422423The MCP Server can be run in [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) transport mode which allows multiple clients to connect to the same server instance via HTTP.424Check if your [MCP client](https://modelcontextprotocol.io/clients) supports streamable http transport before attempting to connect to MCP server in this mode.425426> Note: This mode does not include authorization support.427428### Usage429430By default, the MCP server will run on port 8000 but this can be configured using the `--port` or `CB_MCP_PORT` environment variable.431432```bash433uvx couchbase-mcp-server \434 --connection-string='<couchbase_connection_string>' \435 --username='<database_username>' \436 --password='<database_password>' \437 --read-only-mode=true \438 --transport=http439```440441The server will be available on http://localhost:8000/mcp. This can be used in MCP clients supporting streamable http transport mode such as Cursor.442443### MCP Client Configuration444445```json446{447 "mcpServers": {448 "couchbase-http": {449 "url": "http://localhost:8000/mcp"450 }451 }452}453```454455## SSE Transport Mode456457There is an option to run the MCP server in [Server-Sent Events (SSE)](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) transport mode.458459> Note: SSE mode has been [deprecated](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse-deprecated) by MCP. We have support for [Streamable HTTP](#streamable-http-transport-mode).460461### Usage462463By default, the MCP server will run on port 8000 but this can be configured using the `--port` or `CB_MCP_PORT` environment variable.464465```bash466uvx couchbase-mcp-server \467 --connection-string='<couchbase_connection_string>' \468 --username='<database_username>' \469 --password='<database_password>' \470 --read-only-mode=true \471 --transport=sse472```473474The server will be available on http://localhost:8000/sse. This can be used in MCP clients supporting SSE transport mode such as Cursor.475476### MCP Client Configuration477478```json479{480 "mcpServers": {481 "couchbase-sse": {482 "url": "http://localhost:8000/sse"483 }484 }485}486```487488## Docker Image489490The MCP server can also be built and run as a Docker container. Prebuilt images can be found on [DockerHub](https://hub.docker.com/r/couchbaseecosystem/mcp-server-couchbase).491492Alternatively, we are part of the [Docker MCP Catalog](https://hub.docker.com/mcp/server/couchbase/overview).493494### Building Image495496```bash497docker build -t mcp/couchbase .498```499500<details>501<summary>Building with Arguments</summary>502If you want to build with the build arguments for commit hash and the build time, you can build using:503504```bash505docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \506 --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \507 -t mcp/couchbase .508```509510**Alternatively, use the provided build script:**511512```bash513./build.sh514```515516This script automatically:517518- Generates git commit hash and build timestamp519- Creates multiple useful tags (`latest`, `<short-commit>`)520- Shows build information and results521- Uses the same arguments as CI/CD builds522523**Verify image labels:**524525```bash526# View git commit hash in image527docker inspect --format='{{index .Config.Labels "org.opencontainers.image.revision"}}' mcp/couchbase:latest528529# View all metadata labels530docker inspect --format='{{json .Config.Labels}}' mcp/couchbase:latest531```532533</details>534535### Running536537The MCP server can be run with the environment variables being used to configure the Couchbase settings. The environment variables are the same as described in the [Configuration section](#server-configuration-for-mcp-clients).538539#### Independent Docker Container540541```bash542docker run --rm -i \543 -e CB_CONNECTION_STRING='<couchbase_connection_string>' \544 -e CB_USERNAME='<database_user>' \545 -e CB_PASSWORD='<database_password>' \546 -e CB_MCP_TRANSPORT='<http|sse|stdio>' \547 -e CB_MCP_READ_ONLY_QUERY_MODE='<true|false>' \548 -e CB_MCP_PORT=9001 \549 -p 9001:9001 \550 mcp/couchbase551```552553The `CB_MCP_PORT` environment variable is only applicable in the case of HTTP transport modes like http and sse.554555#### MCP Client Configuration556557The Docker image can be used in `stdio` transport mode with the following configuration.558559```json560{561 "mcpServers": {562 "couchbase-mcp-docker": {563 "command": "docker",564 "args": [565 "run",566 "--rm",567 "-i",568 "-e",569 "CB_CONNECTION_STRING=<couchbase_connection_string>",570 "-e",571 "CB_USERNAME=<database_user>",572 "-e",573 "CB_PASSWORD=<database_password>",574 "mcp/couchbase"575 ]576 }577 }578}579```580581Notes582583- The `couchbase_connection_string` value depends on whether the Couchbase server is running on the same host machine, in another Docker container, or on a remote host. If your Couchbase server is running on your host machine, your connection string would likely be of the form `couchbase://host.docker.internal`. For details refer to the [docker documentation](https://docs.docker.com/desktop/features/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host).584- You can specify the container's networking using the `--network=<your_network>` option. The network you choose depends on your environment; the default is `bridge`. For details, refer to [network drivers in docker](https://docs.docker.com/engine/network/drivers/).585586### Risks Associated with LLMs587588- The use of large language models and similar technology involves risks, including the potential for inaccurate or harmful outputs.589- Couchbase does not review or evaluate the quality or accuracy of such outputs, and such outputs may not reflect Couchbase's views.590- You are solely responsible for determining whether to use large language models and related technology, and for complying with any license terms, terms of use, and your organization's policies governing your use of the same.591592### Managed MCP Server593594The Couchbase MCP server can also be used as a managed server in your agentic applications via [Smithery.ai](https://smithery.ai/server/@Couchbase-Ecosystem/mcp-server-couchbase).595596## Troubleshooting Tips597598- Ensure the path to your MCP server repository is correct in the configuration if running from source.599- Verify that your Couchbase connection string, database username, password or the path to the certificates are correct.600- If using Couchbase Capella, ensure that the cluster is [accessible](https://docs.couchbase.com/cloud/clusters/allow-ip-address.html) from the machine where the MCP server is running.601- Check that the database user has proper permissions to access at least one bucket.602- Confirm that the `uv` package manager is properly installed and accessible. You may need to provide absolute path to `uv`/`uvx` in the `command` field in the configuration.603- Check the logs for any errors or warnings that may indicate issues with the MCP server. The location of the logs depend on your MCP client.604- If you are observing issues running your MCP server from source after updating your local MCP server repository, try running `uv sync` to update the [dependencies](https://docs.astral.sh/uv/concepts/projects/sync/#syncing-the-environment).605606## Integration testing607608We provide high-level MCP integration tests to verify that the server exposes the expected tools and that they can be invoked against a demo Couchbase cluster.6096101. Export demo cluster credentials:611 - `CB_CONNECTION_STRING`612 - `CB_USERNAME`613 - `CB_PASSWORD`614 - Optional: `CB_MCP_TEST_BUCKET` (a bucket to probe during the tests)6152. Run the tests:616617```bash618uv run pytest tests/ -v619```620621---622623## 👩💻 Contributing624625We welcome contributions from the community! Whether you want to fix bugs, add features, or improve documentation, your help is appreciated.626627If you need help, have found a bug, or want to contribute improvements, the best place to do that is right here — by [opening a GitHub issue](https://github.com/Couchbase-Ecosystem/mcp-server-couchbase/issues).628629### For Developers630631If you're interested in contributing code or setting up a development environment:632633📖 **See [CONTRIBUTING.md](CONTRIBUTING.md)** for comprehensive developer setup instructions, including:634635- Development environment setup with `uv`636- Code linting and formatting with Ruff637- Pre-commit hooks installation638- Project structure overview639- Development workflow and practices640641### Quick Start for Contributors642643```bash644# Clone and setup645git clone https://github.com/Couchbase-Ecosystem/mcp-server-couchbase.git646cd mcp-server-couchbase647648# Install with development dependencies649uv sync --extra dev650651# Install pre-commit hooks652uv run pre-commit install653654# Run linting655./scripts/lint.sh656```657658---659660## 📢 Support Policy661662We truly appreciate your interest in this project!663This project is **Couchbase community-maintained**, which means it's **not officially supported** by our support team. However, our engineers are actively monitoring and maintaining this repo and will try to resolve issues on a best-effort basis.664665Our support portal is unable to assist with requests related to this project, so we kindly ask that all inquiries stay within GitHub.666667Your collaboration helps us all move forward together — thank you!668
Full transparency — inspect the skill content before installing.