Couchbase MCP Server

What is Couchbase MCP Server about?

Couchbase MCP Server provides a bridge between large language models and Couchbase clusters, exposing database actions (list scopes/collections, get/upsert/delete documents, run SQL++ queries) via the Model Context Protocol.

How to use Couchbase MCP Server?

Install – either from the PyPI package couchbase-mcp-server using uvx couchbase-mcp-server or run the source code with uv.
Configure – set required environment variables (CB_CONNECTION_STRING, CB_USERNAME, CB_PASSWORD, CB_BUCKET_NAME) and optional ones such as CB_MCP_READ_ONLY_QUERY_MODE, CB_MCP_TRANSPORT, CB_MCP_HOST, CB_MCP_PORT.
Add to MCP client – include the server definition in the client’s mcpServers JSON (Claude Desktop, Cursor, Windsurf, etc.).
Start the server – run the command; the server will listen on the chosen transport (stdio, HTTP, or SSE) and become available to the LLM for natural‑language driven database interactions.

Key features of Couchbase MCP Server

List all scopes and collections in a bucket.
Retrieve the schema of a collection.
Get, upsert, and delete documents by ID within any scope/collection.
Execute SQL++ queries with an optional read‑only mode (default) to prevent data‑changing statements.
Server status endpoint and cluster‑credential health check.
Multiple transport modes: stdio (default), streamable HTTP, and deprecated SSE.
Docker image for containerized deployment.
Fully configurable via environment variables or CLI flags.

Use cases of Couchbase MCP Server

Agentic applications that need to query or modify Couchbase data based on natural language prompts.
Chat‑based data assistants where users ask an LLM to fetch or update documents without writing code.
Rapid prototyping of AI‑driven workflows that require direct access to Couchbase collections.
Integration with IDE‑level AI tools (e.g., Claude Desktop, Cursor) to explore or manipulate database content during development.

FAQ from the Couchbase MCP Server

Q: Can the server run write queries (INSERT/UPDATE) via SQL++? A: By default CB_MCP_READ_ONLY_QUERY_MODE is true, which blocks data‑modifying queries. Set it to false to allow writes, but the server still enforces ID‑based upserts/deletes.
Q: Which transport should I choose? A: Use stdio for local client integrations, http for multiple clients sharing one instance, and avoid sse as it is deprecated.
Q: Is authentication supported for HTTP transport? A: No, the streamable HTTP mode does not include built‑in authorization; secure the endpoint with external mechanisms if needed.
Q: How do I run the server in Docker? A: Pull couchbaseecosystem/mcp-server-couchbase from Docker Hub and supply the same environment variables; map the port if using HTTP/SSE.
Q: What Python version is required? A: Python 3.10 or higher.

An MCP server implementation of Couchbase that allows LLMs to directly interact with Couchbase clusters.

Features

Get a list of all the scopes and collections in the specified bucket
Get the structure for a collection
Get a document by ID from a specified scope and collection
Upsert a document by ID to a specified scope and collection
Delete a document by ID from a specified scope and collection
Run a SQL++ query on a specified scope
- There is an option in the MCP server, CB_MCP_READ_ONLY_QUERY_MODE that is set to true by default to disable running SQL++ queries that change the data or the underlying collection structure. Note that the documents can still be updated by ID.
Get the status of the MCP server
Check the cluster credentials by connecting to the cluster

Prerequisites

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 client such as Claude Desktop 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 pre built PyPI package or the source using uv.

Running from PyPI

We publish a pre built PyPI package for the MCP server.

Server Configuration using Pre built Package for MCP Clients

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

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.

git clone https://github.com/Couchbase-Ecosystem/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",
        "CB_BUCKET_NAME": "bucket_name"
      }
    }
  }
}

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 bucket access	Required
`CB_PASSWORD`	`--password`	Password for authentication	Required
`CB_BUCKET_NAME`	`--bucket-name`	Name of the bucket to access	Required
`CB_MCP_READ_ONLY_QUERY_MODE`	`--read-only-query-mode`	Prevent data modification queries	`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`

You can also check the version of the server using:

uvx couchbase-mcp-server --version

Client Specific Configuration

Follow the steps below to use Couchbase MCP server with Claude Desktop MCP client

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.
- 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 to the mcpServers section.
Restart Claude Desktop to apply the changes.
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.

Follow steps below to use Couchbase MCP server with Cursor:

Install Cursor on your machine.
In Cursor, go to Cursor > Cursor Settings > Tools & Integrations > MCP Tools. Also, checkout the docs on setting up MCP server configuration from Cursor.
Specify the same configuration. You may need to add the server configuration under a parent key of mcpServers.
Save the configuration.
You will see couchbase as an added server in MCP servers list. Refresh to see if server is enabled.
You can now use the Couchbase MCP server in Cursor to query your Couchbase cluster using natural language and perform CRUD operations on documents.

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

Logs

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

Follow the steps below to use the Couchbase MCP server with Windsurf Editor.

Install Windsurf Editor on 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 the official documentation.
Click on Add Server and then Add custom server. On the configuration that opens in the editor, add the Couchbase MCP Server configuration from above.
Save the configuration.
You will see couchbase as an added server in MCP Servers list under Advanced Settings. Refresh to see if server is enabled.
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.

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

Streamable HTTP Transport Mode

The MCP Server can be run in Streamable HTTP transport mode which allows multiple clients to connect to the same server instance via HTTP. Check if your MCP client supports streamable http transport before attempting to connect to MCP server in this mode.

Note: This mode does not include authorization support.

Usage

By default, the MCP server will run on port 8000 but this can be configured using the --port or CB_MCP_PORT environment variable.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --bucket-name='<couchbase_bucket_to_use>' \
  --read-only-query-mode=true \
  --transport=http

The server will be available on http://localhost:8000/mcp. This can be used in MCP clients supporting streamable http transport mode such as Cursor.

MCP Client Configuration

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

SSE Transport Mode

There is an option to run the MCP server in Server-Sent Events (SSE) transport mode.

Note: SSE mode has been deprecated by MCP. We have support for Streamable HTTP.

Usage

By default, the MCP server will run on port 8000 but this can be configured using the --port or CB_MCP_PORT environment variable.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --bucket-name='<couchbase_bucket_to_use>' \
  --read-only-query-mode=true \
  --transport=sse

The server will be available on http://localhost:8000/sse. This can be used in MCP clients supporting SSE transport mode such as Cursor.

MCP Client Configuration

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

Docker Image

The MCP server can also be built and run as a Docker container. Prebuilt images can be found on DockerHub.

Alternatively, we are part of the Docker MCP Catalog.

Building Image

docker build -t mcp/couchbase .

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 build script:

./build.sh

This script automatically:

Generates git commit hash and build timestamp
Creates multiple useful tags (latest, <short-commit>)
Shows build information and results
Uses the same arguments as CI/CD builds

Verify image labels:

# View git commit hash in image
docker inspect --format='{{index .Config.Labels "org.opencontainers.image.revision"}}' mcp/couchbase:latest

# View all metadata labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase:latest

Running

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

Independent Docker Container

docker run --rm -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_BUCKET_NAME='<bucket_name>' \
  -e CB_MCP_TRANSPORT='<http|sse|stdio>' \
  -e CB_MCP_READ_ONLY_QUERY_MODE='<true|false>' \
  -e CB_MCP_PORT=9001 \
  -p 9001:9001 \
  mcp/couchbase

The CB_MCP_PORT environment variable is only applicable in the case of HTTP transport modes like http and sse.

MCP Client Configuration

The Docker image can be used in stdio transport mode with the following configuration.

{
  "mcpServers": {
    "couchbase-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CB_CONNECTION_STRING=<couchbase_connection_string>",
        "-e",
        "CB_USERNAME=<database_user>",
        "-e",
        "CB_PASSWORD=<database_password>",
        "-e",
        "CB_BUCKET_NAME=<bucket_name>",
        "mcp/couchbase"
      ]
    }
  }
}

Notes

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

Risks Associated with LLMs

The use of large language models and similar technology involves risks, including the potential for inaccurate or harmful outputs.
Couchbase does not review or evaluate the quality or accuracy of such outputs, and such outputs may not reflect Couchbase's views.
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.

Managed MCP Server

The Couchbase MCP server can also be used as a managed server in your agentic applications via Smithery.ai.

Troubleshooting Tips

Ensure the path to your MCP server repository is correct in the configuration if running from source.
Verify that your Couchbase connection string, database username, password and bucket name are correct.
If using Couchbase Capella, ensure that the cluster is accessible from the machine where the MCP server is running.
Check that the database user has proper permissions to access the specified bucket.
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.
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.
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.

👩‍💻 Contributing

We welcome contributions from the community! Whether you want to fix bugs, add features, or improve documentation, your help is appreciated.

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

For Developers

If you're interested in contributing code or setting up a development environment:

📖 See CONTRIBUTING.md for comprehensive developer setup instructions, including:

Development environment setup with uv
Code linting and formatting with Ruff
Pre-commit hooks installation
Project structure overview
Development workflow and practices

Quick Start for Contributors

# Clone and setup
git clone https://github.com/Couchbase-Ecosystem/mcp-server-couchbase.git
cd mcp-server-couchbase

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

# Run linting
./scripts/lint.sh

📢 Support Policy

We truly appreciate your interest in this project! This 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.

Our support portal is unable to assist with requests related to this project, so we kindly ask that all inquiries stay within GitHub.

Your collaboration helps us all move forward together — thank you!

Couchbase MCP Server