Couchbase MCP Server

Couchbase MCP Server is a self-hosted Model Context Protocol (MCP) server that connects AI agents and LLM-powered assistants — Claude, Cursor, Windsurf, VS Code Copilot, and other MCP clients — to data in Couchbase clusters, whether hosted on Capella or self-managed. MCP is an open standard for letting AI assistants call tools and query external data sources; this server implements that standard for Couchbase, so an AI agent can inspect your cluster, run SQL++ queries, read and write documents, and analyze query performance using natural language instead of hand-written code.

It provides tools across categories including Cluster Health, Data Schema, Key-Value, Query, and Performance — with safety controls via read-only mode (on by default) and fine-grained tool disabling, so you can let an AI agent explore and query your data without risking unintended writes. It supports both STDIO and Streamable HTTP transports.

Couchbase MCP server is distributed as a Python Package Index (PyPI) package and via Docker. Enterprise support for Couchbase MCP Server is available by licensing Couchbase AI Data Plane, which also entitles use and enterprise support of Couchbase Agent Memory and Couchbase Agent Catalog.

For full documentation, visit mcp-server.couchbase.com.

For full documentation, visit docs.couchbase.com/mcp-server.

Table of Contents

• Why Couchbase MCP Server
• Example Prompts
• Features/Tools
• Prerequisites
• Configuration
• Streamable HTTP Transport Mode
• SSE Transport Mode
• OAuth 2.1 Authorization
• Docker Image
• Usage Data Collection
• Troubleshooting Tips
• Integration Testing
• FAQ
• Contributing
• Support Policy

Why Couchbase MCP Server

• Safe by default — write operations (document upserts/inserts/deletes and data-modifying SQL++ queries) are blocked unless you explicitly set `CB_MCP_READ_ONLY_MODE=false`, and individual tools can be disabled or gated behind user confirmation.
• Works with Capella and self-managed clusters — the same configuration connects to Couchbase Capella (fully managed) or a self-hosted Couchbase Server cluster.
• RBAC-aware — tool disabling is a convenience layer for guiding LLM behavior; the underlying Couchbase user's role-based access control remains the authoritative security boundary.
• Production transports — run over STDIO for local desktop clients, or Streamable HTTP with optional OAuth 2.1 (JWT/JWKS, provider-agnostic — Auth0, Okta, Keycloak, Entra, Cognito, etc.) for shared/remote deployments.
• Any MCP client — tested with Claude Desktop, Cursor, Windsurf, VS Code, and JetBrains AI Assistant/Junie; works with any client implementing the MCP specification.

Example Prompts

Once the server is connected, you can talk to your Couchbase cluster in natural language through your AI assistant. For example:

• "What buckets, scopes, and collections do I have in this cluster, and what's the schema of the `orders` collection?"
• "Run a SQL++ query to find the 10 most recent documents in the `users` collection `where status = 'active'`."
• "What are the 5 slowest queries on this cluster in the last hour, and are any of them missing a covering index?"
• "Check whether this cluster is healthy and tell me which services are running."
• "Insert a new document into the `products` collection with these fields: ..." (requires `CB_MCP_READ_ONLY_MODE=false`)

Features/Tools

Cluster setup & health tools

Data model & schema discovery tools

Document KV operations tools

Query and indexing tools

Query performance analysis tools

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

Basic Authentication

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

or

mTLS

{
  "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

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.

{
  "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:

Read-Only Mode Configuration

`CB_MCP_READ_ONLY_MODE` is the single switch controlling write operations:

• When `true` (default): All write operations (KV, Query, scope/collection management, and index management) are disabled. All write tools (KV: upsert, insert, replace, delete, sub-document mutate; scope/collection management: create_scope, create_collection, delete_scope, delete_collection; index management: create_index, build_index, drop_index) are not loaded and will not be available to the LLM, and SQL++ queries that modify data or structure are blocked.
• When `false`: All 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:

# 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):

# 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`):

# 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:

{
  "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):

{
  "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:

# 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:

uvx couchbase-mcp-server --version

Logging

The MCP server logs to `stderr` by default. Logging is configured with the `CB_MCP_LOG_*` variables listed in Additional Configuration:

• `CB_MCP_LOG_LEVEL` — how much is logged: `info` (the default) logs lifecycle events and tool invocations, `debug` adds verbose internal detail, and `off` disables all logging.
• `CB_MCP_LOG_SINKS` — where logs go: `stderr` (the default), per-level rotating files (`file`), or both. With `file`, one file is written per level (for example `mcp_server.info.log` and `mcp_server.error.log`) at the path set by `CB_MCP_LOG_FILE`.
• Rotation size — `CB_MCP_LOG_ROTATION_MAX_SIZE_MB` is the global size (in MB) at which each per-level file rotates. Override individual levels with `CB_MCP_LOG__ROTATION_MAX_SIZE_MB` (`ERROR`/`WARNING`/`INFO`/`DEBUG`), also in MB, which inherit the global when unset. A size of `0` (global or per-level) is invalid and falls back to the default (1 MB) with a startup warning. `CB_MCP_LOG_MAX_BYTES` (bytes) is deprecated but still honored for backward compatibility; it is ignored when `CB_MCP_LOG_ROTATION_MAX_SIZE_MB` is also set, and prints a deprecation warning at startup.
• Retention — `CB_MCP_LOG_RETENTION_BACKUP_COUNT` sets how many rotated backups are kept per level (excluding the live file); the default of `1` preserves the previous behaviour. Override individual levels with `CB_MCP_LOG__RETENTION_BACKUP_COUNT` (`ERROR`/`WARNING`/`INFO`/`DEBUG`), which inherit the global value when unset. Set a count to `0` to keep only the live file for that level — it is still capped by the rotation size (reset on rollover rather than backed up).
• Server-config snapshot — when the `file` sink is active, a one-shot record (OS, Python, dependency versions, transport, resolved logging config, and redacted server config) is written as JSON to a dedicated `mcp_server_config.log.json` file (derived from the `CB_MCP_LOG_FILE` base). It is overwritten on each start, so support always has the current config and it never scrolls out of a rotating log.

# Enable debug logging to both stderr and rotating per-level files
uvx couchbase-mcp-server --log-level=debug --log-sinks=stderr,file

# Keep 30 rotated ERROR backups but only the live DEBUG file
uvx couchbase-mcp-server --log-level=debug --log-sinks=file \
  --log-error-retention-backup-count=30 --log-debug-retention-backup-count=0

For more details, see the documentation.

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.

Open the configuration file and add the 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.

Cursor

Follow steps below to use Couchbase MCP server with Cursor:

1. Install Cursor 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 from Cursor.

3. Specify the same 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]: https://cursor.com/en-US/install-mcp?name=Couchbase&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJjb3VjaGJhc2UtbWNwLXNlcnZlciJdLCJlbnYiOnsiQ0JfQ09OTkVDVElPTl9TVFJJTkciOiJjb3VjaGJhc2VzOi8vY29ubmVjdGlvbi1zdHJpbmciLCJDQl9VU0VSTkFNRSI6InVzZXJuYW1lIiwiQ0JfUEFTU1dPUkQiOiJwYXNzd29yZCJ9fQ%3D%3D

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.

Windsurf Editor

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

1. Install Windsurf Editor on your machine.

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

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

4. Save the configuration.

5. You will see couchbase as an added server in MCP Servers list under Advanced Settings. Refresh to see if server is enabled.

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

VS Code

Follow the steps below to use the Couchbase MCP server with VS Code.

1. Install VS Code

2. Following are a couple of ways to configure the MCP server.

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

3. Once you save the file, the server starts and a small action list appears with `Running|Stop|n Tools|More..`.

4. Click on the options from the option list to `Start`/`Stop`/manage the server.

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

Logs:

In the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`),

• run MCP: List Servers command and pick the couchbase server
• choose “Show Output” to see its logs in the Output tab.

JetBrains IDEs

Follow the steps below to use the Couchbase MCP server with JetBrains IDEs

1. Install any one of the JetBrains IDEs

2. Install any one of the JetBrains plugins - AI Assistant or Junie

3. Navigate to Settings > Tools > AI Assistant or Junie > MCP Server

4. Click "+" to add the Couchbase MCP configuration and click Save.

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

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

Logs:

The log file can be explored at Help > Show Log in Finder (Explorer) > mcp > couchbase

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: OAuth 2.1 authorization is supported on this transport. See OAuth 2.1 Authorization. Without OAuth configured, the HTTP endpoint is unauthenticated.

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='' \
  --username='' \
  --password='' \
  --read-only-mode=true \
  --transport=http

The server will be available on . 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.

SSE: 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='' \
  --username='' \
  --password='' \
  --read-only-mode=true \
  --transport=sse

The server will be available on . This can be used in MCP clients supporting SSE transport mode such as Cursor.

SSE: MCP Client Configuration

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

OAuth 2.1 Authorization

When running with `--transport=http`, the MCP server can act as an OAuth 2.1 resource server: it validates incoming bearer JWTs against your identity provider's JWKS. It is provider-agnostic (any OAuth 2.1 / OIDC provider that publishes a JWKS — Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra, etc.) and does not issue tokens or manage users. OAuth settings are ignored on `stdio`.

OAuth is configured with the `CB_MCP_OAUTH_*` variables listed in Additional Configuration:

• OAuth activates only when all three of `CB_MCP_OAUTH_JWT_JWKS_URI`, `CB_MCP_OAUTH_JWT_ISSUER`, and `CB_MCP_OAUTH_JWT_AUDIENCE` are set; setting only some of them fails at startup.
• Setting `CB_MCP_OAUTH_MCP_BASE_URL` additionally publishes RFC 9728 Protected Resource Metadata so PRM-aware clients can discover the authorization server.
• Access is gated by two scopes read from the token's `scope`/`scp` claim: `couchbase-mcp:read` (read tools, including SQL++) and `couchbase-mcp:write` (write tools: KV mutations, scope/collection management, and index management). Full access requires both. If your IdP can't emit those canonical labels, override them with `CB_MCP_OAUTH_SCOPE_READ_LABEL` / `CB_MCP_OAUTH_SCOPE_WRITE_LABEL`.

uvx couchbase-mcp-server \
  --connection-string='' \
  --username='' \
  --password='' \
  --transport=http \
  --oauth-jwks-uri='https://auth.example.com/.well-known/jwks.json' \
  --oauth-issuer='https://auth.example.com/' \
  --oauth-audience='couchbase-mcp-server' \
  --oauth-mcp-base-url=''

For full details, see the documentation.

Docker Image

The MCP server can also be built and run as a Docker container. Prebuilt images can be found on DockerHub or pulled via `docker pull docker.io/couchbase/mcp-server:latest`.

Alternatively, we are part of the Docker MCP Catalog.

Building Image

docker build -t mcp/couchbase-src .

Building with Arguments

If you want to build with the build arguments for commit hash and the build time, you can build using:

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

Alternatively, use the provided build script:

# Build with default image name (mcp/couchbase-src)
./build.sh

# Build with custom image name
./build.sh my-custom/image-name

This script automatically:

• Accepts an optional image name parameter (defaults to `mcp/couchbase-src`)
• Generates git commit hash and build timestamp
• Creates multiple useful tags (`latest`, ``)
• 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-src:latest

# View all metadata labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src: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 Additional Configuration section.

Independent Docker Container

docker run --rm -i \
  -e CB_CONNECTION_STRING='' \
  -e CB_USERNAME='' \
  -e CB_PASSWORD='' \
  -e CB_MCP_TRANSPORT='' \
  -e CB_MCP_READ_ONLY_MODE='' \
  -e CB_MCP_CONFIRMATION_REQUIRED_TOOLS='delete_document_by_id' \
  -e CB_MCP_PORT=9001 \
  -e CB_MCP_HOST=0.0.0.0 \
  -p 9001:9001 \
  mcp/couchbase-src

The `CB_MCP_PORT` and `CB_MCP_HOST` environment variables are only applicable in the case of HTTP transport modes like http and sse.

Docker: 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=",
        "-e",
        "CB_USERNAME=",
        "-e",
        "CB_PASSWORD=",
        "mcp/couchbase-src"
      ]
    }
  }
}

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

Usage Data Collection

This product automatically collects usage and performance data (such as product name and version) and browser information (such as IP address) (collectively, "Usage Data"). Couchbase uses Usage Data, along with other data you may provide to Couchbase (such as your user name or email address), to develop and improve our products as well as inform our sales and marketing programs. We do not access or collect any data you store in Couchbase products. We use Usage Data to understand aggregate usage patterns and make our products more useful to you. For more information on how Couchbase collects, protects, and processes information, please refer to the Couchbase Privacy Policy viewable at https://www.couchbase.com/privacy-policy.

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 or the path to the certificates 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 at least one 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.

Integration testing

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

1. Export demo cluster credentials:

2. Run the tests:

uv run pytest tests/ -v

FAQ

What is the Couchbase MCP Server? It's a self-hosted implementation of the Model Context Protocol that lets AI assistants and agents (Claude, Cursor, Windsurf, VS Code Copilot, JetBrains AI Assistant/Junie, and any other MCP client) query and, optionally, modify data in a Couchbase cluster using natural language.

How do I connect Claude Desktop to Couchbase? Install the server with `uvx couchbase-mcp-server` (or run it from source or Docker), then add its configuration to Claude Desktop's `claude_desktop_config.json` as shown in Configuration. Restart Claude Desktop and it will pick up the new tools.

Can I use this with Couchbase Capella? Yes. The same `CB_CONNECTION_STRING/CB_USERNAME/CB_PASSWORD` (or mTLS certificate) configuration works for both Couchbase Capella and self-managed Couchbase Server clusters.

Is it safe to let an AI agent write to my database? By default, `CB_MCP_READ_ONLY_MODE` is true, so all write operations — document upserts/inserts/replaces/deletes and data-modifying SQL++ statements — are disabled and the write tools aren't even loaded. You can also disable individual tools (see Disabling Tools) or require explicit user confirmation before specific tools run (see Elicitation/Confirmation). Tool-level controls guide LLM behavior; your Couchbase user's RBAC permissions remain the real security boundary.

Can I run natural-language queries against my data without writing SQL++ myself? Yes — ask your AI assistant a question in plain English (e.g. "show me the 10 most recent orders over $100") and it can translate that into a SQL++ query using the `run_sql_plus_plus_query` tool. You can also ask the assistant to `explain_sql_plus_plus_query` a query or ask the index advisor for recommendations.

What's the difference between STDIO, Streamable HTTP, and SSE transport? STDIO is for a single local MCP client (e.g. Claude Desktop) launching the server as a subprocess. Streamable HTTP lets multiple clients share one running server instance over HTTP, and supports OAuth 2.1. SSE is the older HTTP transport, now deprecated by the MCP spec in favor of Streamable HTTP — see Streamable HTTP Transport Mode.

Is this officially supported by Couchbase? This project is Couchbase community-maintained — see Support Policy. Enterprise support is available separately through Couchbase AI Data Plane.

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