mcp-server-couchbase

What is mcp-server-couchbase?

mcp-server-couchbase is a server implementation for the Model Context Protocol (MCP) that allows Large Language Models (LLMs) to directly interact with Couchbase clusters. It enables users to perform various operations on Couchbase data using natural language through an MCP client.

How to use mcp-server-couchbase?

Prerequisites: Ensure you have Python 3.10 or higher, a running Couchbase cluster (e.g., Couchbase Capella free tier), and uv installed. You also need an MCP client like Claude Desktop or Cursor.
Configuration:
- Clone the repository: git clone https://github.com/Couchbase-Ecosystem/mcp-server-couchbase.git
- Configure the server by setting environment variables such as CB_CONNECTION_STRING, CB_USERNAME, CB_PASSWORD, and CB_BUCKET_NAME. The READ_ONLY_QUERY_MODE can be set to control whether SQL++ queries can modify data (defaults to true).
- Integrate with an MCP client (e.g., Claude Desktop, Cursor, Windsurf Editor) by adding the server configuration to the client's settings. This typically involves specifying the command to run the server (uv run src/mcp_server.py) and the environment variables.
Running the Server:
- Locally: Use uv to run the server, providing necessary connection details.
- Docker: Build a Docker image (docker build -t mcp/couchbase .) and run it with the required environment variables.
- SSE Mode: The server can also run in Server-Sent Events (SSE) transport mode, though this is deprecated by MCP.

Key Features of mcp-server-couchbase

Data Interaction: Perform CRUD operations (Get, Upsert, Delete) on documents within specified scopes and collections.
Data Retrieval: Get a list of all scopes and collections in a bucket, and retrieve the structure for a collection.
SQL++ Queries: Execute SQL++ queries on a specified scope. The READ_ONLY_QUERY_MODE can be enabled to prevent data modification through queries.
LLM Integration: Enables LLMs to interact with Couchbase data using natural language.
Client Compatibility: Works with various MCP clients like Claude Desktop, Cursor, and Windsurf Editor.
Docker Support: Can be easily deployed using Docker containers.

Use Cases of mcp-server-couchbase

Natural Language Data Access: Allow users to query and manipulate Couchbase data using natural language prompts through LLM interfaces.
Simplified Data Operations: Enable developers and data analysts to perform common database operations without writing explicit code, by leveraging LLM capabilities.
Agentic Applications: Integrate Couchbase data into agentic workflows where LLMs need to access and act upon structured data.

FAQ about mcp-server-couchbase

What are the prerequisites? Python 3.10+, a running Couchbase cluster, uv installed, and an MCP client.
How do I configure the server? Clone the repository and set environment variables like CB_CONNECTION_STRING, CB_USERNAME, CB_PASSWORD, and CB_BUCKET_NAME. Refer to the configuration section for details.
How do I connect an MCP client? Add the server's configuration (command, arguments, environment variables) to your MCP client's settings file (e.g., claude_desktop_config.json for Claude Desktop).
Can I run SQL++ queries that modify data? Yes, but you need to set READ_ONLY_QUERY_MODE to false. By default, it's true, disabling data modification queries.
Where can I find logs for troubleshooting? Log locations vary by client. For Claude Desktop, they are in ~/Library/Logs/Claude (macOS) or %APPDATA%\Claude\Logs (Windows). For Cursor, check the "Output" panel and select "Cursor MCP".
Is this project officially supported? No, this is a community-maintained project. Support and contributions are handled through GitHub issues.

Risks Associated with LLMs

LLM outputs may be inaccurate or harmful.
Couchbase does not endorse or verify the quality of LLM outputs.
Users are responsible for their use of LLMs and compliance with relevant policies.

Couchbase MCP Server

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

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

Clone the repository to your local machine.

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

Server Configuration 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"
      }
    }
  }
}

The server can be configured using environment variables. The following variables are supported:

CB_CONNECTION_STRING: The connection string to the Couchbase cluster
CB_USERNAME: The username with access to the bucket to use to connect
CB_PASSWORD: The password for the username to connect
CB_BUCKET_NAME: The name of the bucket that the server will access
READ_ONLY_QUERY_MODE: Setting to configure whether SQL++ queries that allow data to be modified are allowed. It is set to True by default.
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.

Claude Desktop

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.

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

Cursor

Follow steps below to use Couchbase MCP server with Cursor:

Install Cursor on your machine.
In Cursor, go to Cursor > Cursor Settings > MCP > Add a new global MCP server. 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.

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

Windsurf Editor

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.

SSE Server 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 are investigating adding support for Streamable HTTP.

Usage

By default, the MCP server will run on port 8080 but this can be configured using the FASTMCP_PORT environment variable.

uv run src/mcp_server.py --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:8080/sse. This can be used in MCP clients supporting SSE transport mode.

Docker Image

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

docker build -t mcp/couchbase .

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

docker run -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 MCP_TRANSPORT='stdio/sse' \
  -e READ_ONLY_QUERY_MODE="true/false" \
  mcp/couchbase

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.
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 in the command field in the configuration.
Check the logs for any errors or warnings that may indicate issues with the MCP server. The server logs are under the name, mcp-server-couchbase.log.

👩‍💻 Contributing

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

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 community-maintained, which means it's not officially supported by our support team.

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

mcp-server-couchbase