Couchbase Model Context Protocol Server Implementation

This repository provides an implementation of the Model Context Protocol (MCP) designed specifically for interacting with Couchbase data platforms, enabling Large Language Models (LLMs) to execute operational tasks directly against the cluster.

Core Capabilities

This server exposes the following functionalities for authorized agents:

• Enumeration of all available data buckets within the cluster.
• Retrieval of scope and collection hierarchies for any given bucket.
• Listing all scopes within a designated bucket.
• Obtaining all collections associated with a specific scope and bucket (Note: Requires the cluster's Query Service to be active).
• Inspecting the schema or structure definition of a designated collection.
• Fetching a specific data item using its unique identifier from a defined scope/collection pair.
• Inserting or updating (Upserting) a document based on its ID within a specified scope and collection.
• Removing a document identified by its ID from a specified scope and collection.
• Executing arbitrary SQL++ queries against a nominated scope.
  • By default, the CB_MCP_READ_ONLY_QUERY_MODE environment setting is activated (true) to prevent queries that alter data or structural definitions. Document modifications via ID-based operations remain permitted.
• Reporting the operational health status of the MCP service itself.
• Validating current connection credentials against the active Couchbase cluster.

Prerequisites for Deployment

To successfully launch and operate this server, ensure the following prerequisites are met:

1. Python Environment: Python version 3.10 or newer.
2. Couchbase Instance: An operational Couchbase cluster is necessary. Leveraging the fully managed Capella free tier is often the simplest initial approach. Follow the provided import guides to load sample data if needed.
3. Package Manager: The uv package manager must be installed to manage dependencies and run the server.
4. MCP Consumer: An established MCP client (e.g., Claude Desktop or Cursor) is required to interface with this backend server. Setup guides for these clients are included below.

Configuration Procedures

The server can be initiated either by pulling the pre-compiled package from PyPI or by building directly from the source repository.

Execution via PyPI

We distribute the ready-to-use package via the official PyPI repository.

Standard Client Configuration (PyPI Launch)

For Basic Credentials:

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

or

For Mutual TLS (mTLS) Authentication:

{ "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 other MCP services are already configured in your client, seamlessly integrate this entry into the existing mcpServers structure.

Execution from Local Source

If you prefer to run or develop from the repository's source code using uv:

Repository Cloning

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

Client Configuration (Source Launch)

This setup pattern is compatible with major MCP clients like Claude Desktop, Cursor, and 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" } } } }

Important: Replace path/to/cloned/repo/mcp-server-couchbase/ with the absolute path to your cloned directory, ensuring the trailing path separator is present.

Note: When integrating with existing client configurations, append this block to the current mcpServers definition.

Server Parameterization Options

The service behavior can be finely tuned via environmental variables or corresponding command-line flags:

Environment Variable	CLI Flag	Purpose	Default Value
CB_CONNECTION_STRING	--connection-string	Defines the URI for connecting to the Couchbase cluster.	Mandatory
CB_USERNAME	--username	Credentials for basic authentication access scope.	Required (or mTLS credentials)
CB_PASSWORD	--password	Secret for basic authentication.	Required (or mTLS credentials)
CB_CLIENT_CERT_PATH	--client-cert-path	Location of the client certificate file when utilizing mTLS.	Required for mTLS
CB_CLIENT_KEY_PATH	--client-key-path	Location of the private key file for mTLS authentication.	Required for mTLS
CB_CA_CERT_PATH	--ca-cert-path	Path to the server's root certificate authority file, needed for verifying self-signed TLS endpoints (unnecessary for Capella).	(None)
CB_MCP_READ_ONLY_QUERY_MODE	--read-only-query-mode	Activates protection to block query operations that mutate data or schema.	true
CB_MCP_TRANSPORT	--transport	Specifies the communication protocol: stdio, http, or sse.	stdio
CB_MCP_HOST	--host	Network address binding for HTTP/SSE modes.	127.0.0.1
CB_MCP_PORT	--port	Network port for HTTP/SSE transport listeners.	8000

Authentication Note: Authentication necessitates either the Username/Password pair OR the Client Certificate/Key paths. Specifying both prioritizes certificate-based security. The CA certificate path is optional unless validating non-standard TLS endpoints.

To ascertain the currently running server version:

bash uvx couchbase-mcp-server --version

Client-Specific Integration Guides

Claude Desktop Integration

To integrate this service with Claude Desktop: 1. Locate and open your configuration file: * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` * Windows: `%APPDATA%\Claude\claude_desktop_config.json` 2. Insert the relevant configuration block from the **[Configuration section](#configuration)** into the `mcpServers` object. 3. Relaunch the Claude Desktop application. 4. You can now leverage natural language commands to query the Couchbase cluster and manage documents via the newly added server. **Log Diagnostics** Troubleshoot connection or operational issues by examining logs at: * macOS: `~/Library/Logs/Claude` * Windows: `%APPDATA%\Claude\Logs` Refer to the [official quickstart guide](https://modelcontextprotocol.io/quickstart/user#troubleshooting) for deeper debugging insight.

Cursor Integration

To enable the Couchbase MCP server within Cursor: 1. Ensure [Cursor](https://cursor.sh/) is installed. 2. Navigate in Cursor to Settings -> Tools & Integrations -> MCP Tools. Consult Cursor's official [MCP setup documentation](https://docs.cursor.com/en/context/mcp#configuring-mcp-servers) for detailed guidance. 3. Input the configuration structure shown earlier, likely nested under an `mcpServers` root key. 4. Save your settings. 5. Verify that 'couchbase' appears as an active server in the MCP list (refresh if necessary). 6. You are now equipped to pose natural language requests to your Couchbase deployment via Cursor. **Log Diagnostics** View the Cursor MCP output channel in the bottom panel (select "Cursor MCP" from the dropdown) to diagnose any startup or communication errors.

Windsurf Editor Integration

Integration steps for [Windsurf Editor](https://windsurf.com/): 1. Install the editor. 2. Access the configuration panel via Command Palette -> Windsurf MCP Configuration Panel, or via Settings -> Advanced -> Cascade -> Model Context Protocol (MCP) Servers. 3. Select "Add Server" followed by "Add custom server". Paste the required [configuration](#configuration) structure into the editor that appears. 4. Save the settings. 5. Confirm 'couchbase' is listed and enabled under Advanced Settings. 6. The server is ready for use within Windsurf for natural language data operations. Refer to the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp) for advanced configuration details.

Streamable HTTP Transport Mode

This server supports the Streamable HTTP transport mechanism, allowing multiple simultaneous client connections over HTTP.

Compatibility Check: Confirm your chosen MCP client explicitly supports Streamable HTTP before proceeding with this mode.

Security Caveat: This transport mechanism does not inherently include authorization checks.

Activation

By default, the listener targets port 8000, adjustable via --port or CB_MCP_PORT.

bash uvx couchbase-mcp-server \ --connection-string='' \ --username='' \ --password='' \ --read-only-query-mode=true \ --transport=http

The service endpoint will be accessible at http://localhost:8000/mcp, compatible with clients like Cursor.

Client Setup for HTTP

{ "mcpServers": { "couchbase-http": { "url": "http://localhost:8000/mcp" } } }

Server-Sent Events (SSE) Transport Mode

An alternative operational mode uses Server-Sent Events (SSE).

Deprecation Notice: MCP has formally deprecated SSE. Streamable HTTP is the recommended successor.

Activation

Configuration is similar to HTTP, utilizing the --transport=sse flag.

bash uvx couchbase-mcp-server \ --connection-string='' \ --username='' \ --password='' \ --read-only-query-mode=true \ --transport=sse

The endpoint will resolve to http://localhost:8000/sse.

Client Setup for SSE

{ "mcpServers": { "couchbase-sse": { "url": "http://localhost:8000/sse" } } }

Docker Image Usage

The server can be containerized. Pre-built images are hosted on DockerHub, and it is discoverable via the Docker MCP Catalog.

Image Compilation

Standard build command:

bash docker build -t mcp/couchbase .

Compilation with Metadata Arguments

To embed Git commit hash and build timestamp into image labels: bash docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \ --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \ -t mcp/couchbase . **Alternatively, use the provided shell script:** bash ./build.sh This script automates tag creation (`latest`, ``), metadata injection, and reports build outcomes. **Verification of Image Labels:** bash # Check revision hash docker inspect --format='{{index .Config.Labels "org.opencontainers.image.revision"}}' mcp/couchbase:latest # View all metadata docker inspect --format='{{json .Config.Labels}}' mcp/couchbase:latest

Container Execution

Configuration within a Docker container relies on setting environment variables matching those detailed in the Configuration section.

Standalone Container Launch

bash docker run --rm -i \ -e CB_CONNECTION_STRING='' \ -e CB_USERNAME='' \ -e CB_PASSWORD='' \ -e CB_MCP_TRANSPORT='' \ -e CB_MCP_READ_ONLY_QUERY_MODE='' \ -e CB_MCP_PORT=9001 \ -p 9001:9001 \ mcp/couchbase

The port mapping (-p) is only relevant when using HTTP or SSE transport protocols.

MCP Client Configuration for Docker (stdio Mode)

This JSON configuration instructs the MCP client to launch the server within a Docker container using stdio transport:

{ "mcpServers": { "couchbase-mcp-docker": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "CB_CONNECTION_STRING=", "-e", "CB_USERNAME=", "-e", "CB_PASSWORD=", "mcp/couchbase" ] } } }

Networking Considerations:

• The format of couchbase_connection_string must account for the host's accessibility from within the container (e.g., use couchbase://host.docker.internal if the cluster runs on the host machine). Consult Docker's networking documentation for host connectivity.
• Container networking mode (e.g., --network=<your_network>) should be specified according to your infrastructure requirements, defaulting to bridge.

Risks Inherent in LLM Technology

• The deployment and use of generative AI models inherently carry risks, including the possibility of generating erroneous or inappropriate content.
• Couchbase does not scrutinize or validate the veracity or safety of outputs produced by these LLMs, and such outputs do not represent Couchbase's official positions.
• Ultimate accountability for the decision to employ LLMs, adherence to associated licensing, terms of service, and organizational compliance mandates rests entirely with the end-user.

Managed Service Option

For deployment within agentic frameworks, this Couchbase MCP server is also available as a managed offering via Smithery.ai.

Diagnostic Guidance

If operational difficulties arise, follow these troubleshooting steps:

• Verify that the path specified for the repository, when running from source, is accurate.
• Double-check the validity of all provided connection strings, user credentials, or certificate file paths.
• If utilizing Couchbase Capella, confirm network access firewall rules permit traffic from the MCP server host to the cluster's IP range (Capella IP Whitelisting).
• Ensure the designated database user possesses sufficient privileges across at least one data bucket.
• Confirm that the uv utility is correctly installed and accessible from the system's PATH. Absolute paths may be required in the client configuration's command field.
• Inspect the client-specific logs for detailed error reporting related to server startup or communication failures.
• If issues persist after repository updates, execute uv sync to refresh and align the project's dependency environment.

---

👩‍💻 Community Contribution Guidelines

We highly value external contributions! Whether you aim to patch defects, introduce new features, or enhance documentation, your input is instrumental.

For assistance, reporting bugs, or submitting improvements, the primary channel is by raising an issue on GitHub.

Developer Setup

To configure a local development environment:

📖 Consult CONTRIBUTING.md for exhaustive instructions, covering:

• Setting up the development workspace using uv.
• Code quality checks using Ruff for linting and formatting.
• Installing required pre-commit hooks.
• Understanding the project's structure.
• Standard development practices.

Rapid Contributor Onboarding

bash

Obtain and prepare the repository

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

Install core and development dependencies

uv sync --extra dev

Activate pre-commit behavior

uv run pre-commit install

Execute linter checks

./scripts/lint.sh

---

📢 Support Acknowledgment

We appreciate your engagement with this project!

Disclaimer: This tool is maintained by the Couchbase community and is not guaranteed official support from Couchbase support channels. While our dedicated engineers actively monitor and maintain this repository, issue resolution will occur on a best-effort basis.

Support inquiries must be directed solely through GitHub. Official support portals cannot handle requests pertaining to this community asset.

Your active participation accelerates progress for everyone involved — thank you for your collaboration!

WIKIPEDIA CONTEXT: Cloud computing, often termed "the cloud," is defined by ISO as "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand."

== Essential Cloud Characteristics (NIST) == In 2011, NIST established five core attributes essential to cloud systems:

1. On-demand self-service: Consumers provision resources (e.g., compute, storage) automatically, without vendor staff intervention.
2. Broad network access: Services are available ubiquitously via standard protocols, supporting diverse client devices (laptops, mobiles, etc.).
3. Resource pooling: Provider infrastructure serves multiple clients concurrently (multi-tenancy), with resources dynamically allocated based on shifting demand.
4. Rapid elasticity: Capabilities can scale up or down quickly (sometimes automatically) to match load fluctuations. From the user's viewpoint, capacity appears virtually limitless.
5. Measured service: Resource consumption (storage, bandwidth, processing time) is automatically tracked, controlled, and reported transparently to both provider and consumer.

ISO has since refined these definitions as of 2023.

== Historical Overview ==

The foundational concepts of cloud computing trace back to the 1960s via time-sharing systems and Remote Job Entry (RJE), where users submitted tasks to mainframe operators. This era focused on optimizing large-scale computation access. The term "cloud" for virtualized environments was popularized around 1994 by General Magic for their Telescript agent universe. David Hoffman, a General Magic communications specialist, is credited with adapting the existing telecom/networking metaphor. The phrase 'cloud computing' gained broader recognition in 1996 following internal business planning documents from Compaq Computer Corporation, outlining ambitions for the future of internet-based computation.