• Repository

Meta

• License Expression: Apache-2.0
  SPDX License Expression
• Author: Developer Experience & Ecosystem, Couchbase
• Requires: Python <3.15, >=3.10
• Provides-Extra: dev

Classifiers

• Development Status
  • 4 - Beta
• Programming Language
  • Python :: 3
• Topic
  • Database

Couchbase MCP Server

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

👁 Docs
👁 License
👁 Python 3.10+
👁 PyPI version
👁 Install in Cursor
👁 Verified on MseeP
👁 Trust Score

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

👁 Couchbase Server MCP server

Features/Tools

Cluster setup & health tools

Tool Name	Description
get_server_configuration_status	Get the status of the MCP server
test_cluster_connection	Check the cluster credentials by connecting to the cluster
get_cluster_health_and_services	Get cluster health status and list of all running services

Data model & schema discovery tools

Tool Name	Description
get_buckets_in_cluster	Get a list of all the buckets in the cluster
get_scopes_in_bucket	Get a list of all the scopes in the specified bucket
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.
get_scopes_and_collections_in_bucket	Get a list of all the scopes and collections in the specified bucket
get_schema_for_collection	Get the structure for a collection

Document KV operations tools

Tool Name	Description
get_document_by_id	Get a document by ID from a specified scope and collection
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.
insert_document_by_id	Insert a new document by ID (fails if document exists). Disabled by default when CB_MCP_READ_ONLY_MODE=true.
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.
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.

Query and indexing tools

Tool Name	Description
list_indexes	List all indexes in the cluster with their definitions, with optional filtering by bucket, scope, collection and index name. Set return_raw_index_stats=true to return the unprocessed index information.
get_index_advisor_recommendations	Get index recommendations from Couchbase Index Advisor for a given SQL++ query to optimize query performance
run_sql_plus_plus_query	Run a SQL++ query on a specified scope. 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). 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.
explain_sql_plus_plus_query	Generate and evaluate an EXPLAIN plan for a SQL++ query. Returns query metadata, extracted plan, and plan evaluation findings.

Query performance analysis tools

Tool Name	Description
get_longest_running_queries	Get longest running queries by average service time
get_most_frequent_queries	Get most frequently executed queries
get_queries_with_largest_response_sizes	Get queries with the largest response sizes
get_queries_with_large_result_count	Get queries with the largest result counts
get_queries_using_primary_index	Get queries that use a primary index (potential performance concern)
get_queries_not_using_covering_index	Get queries that don't use a covering index
get_queries_not_selective	Get queries that are not selective (index scans return many more documents than final result)

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

gitclonehttps://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"
}
}
}
}

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 access to required buckets for basic authentication	Required (or Client Certificate and Key needed for mTLS)
CB_PASSWORD	--password	Password for basic authentication	Required (or Client Certificate and Key needed for mTLS)
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)
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)
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
CB_MCP_READ_ONLY_MODE	--read-only-mode	Prevent all data modifications (KV and Query). When enabled, KV write tools are not loaded.	true
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
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
CB_MCP_DISABLED_TOOLS	--disabled-tools	Tools to disable (see Disabling Tools)	None
CB_MCP_CONFIRMATION_REQUIRED_TOOLS	--confirmation-required-tools	Tools that require explicit user confirmation before execution via MCP elicitation (see Elicitation/Confirmation Required Tools)	None

Read-Only Mode Configuration

The MCP server provides two configuration options for controlling write operations:

CB_MCP_READ_ONLY_MODE (Recommended)

• 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.
• When false: KV write tools are loaded and available.

CB_MCP_READ_ONLY_QUERY_MODE (Deprecated)

• This option only controls SQL++ query-based writes but does not prevent KV write operations.
• Deprecated: Use CB_MCP_READ_ONLY_MODE instead for comprehensive protection.

Mode Behavior Truth Table:

READ_ONLY_MODE	READ_ONLY_QUERY_MODE	Result
true	true	Read-only KV and Query operations. All writes disabled.
true	false	Read-only KV and Query operations. All writes disabled.
false	true	Only Query writes disabled. KV writes allowed.
false	false	All KV and Query operations allowed.

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.

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
uvxcouchbase-mcp-server--disabled-toolsupsert_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
uvxcouchbase-mcp-server--disabled-toolsdisabled_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
uvxcouchbase-mcp-server--confirmation-required-toolsdelete_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:

uvxcouchbase-mcp-server--version

Client Specific Configuration

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.

uvxcouchbase-mcp-server\
--connection-string='<couchbase_connection_string>'\
--username='<database_username>'\
--password='<database_password>'\
--read-only-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.

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.

uvxcouchbase-mcp-server\
--connection-string='<couchbase_connection_string>'\
--username='<database_username>'\
--password='<database_password>'\
--read-only-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.

SSE: 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 or pulled via docker pull couchbase.docker.scarf.sh/couchbaseecosystem/mcp-server-couchbase.

Alternatively, we are part of the Docker MCP Catalog.

Building Image

dockerbuild-tmcp/couchbase-src.

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

dockerrun--rm-i\
-eCB_CONNECTION_STRING='<couchbase_connection_string>'\
-eCB_USERNAME='<database_user>'\
-eCB_PASSWORD='<database_password>'\
-eCB_MCP_TRANSPORT='<http|sse|stdio>'\
-eCB_MCP_READ_ONLY_MODE='<true|false>'\
-eCB_MCP_CONFIRMATION_REQUIRED_TOOLS='delete_document_by_id'\
-eCB_MCP_PORT=9001\
-eCB_MCP_HOST=0.0.0.0\
-p9001: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=<couchbase_connection_string>",
"-e",
"CB_USERNAME=<database_user>",
"-e",
"CB_PASSWORD=<database_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=<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 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:
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • Optional: CB_MCP_TEST_BUCKET (a bucket to probe during the tests)
2. Run the tests:

uvrunpytesttests/-v

---

👩‍💻 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
gitclonehttps://github.com/Couchbase-Ecosystem/mcp-server-couchbase.git
cdmcp-server-couchbase

# Install with development dependencies
uvsync--extradev

# Install pre-commit hooks
uvrunpre-commitinstall

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

Verified details

These details have been verified by PyPI

Project links

• Homepage
• Issues

Owner

• Couchbase, Inc.

GitHub Statistics

Maintainers

👁 Avatar for AayushTyagi1 from gravatar.com
AayushTyagi1 👁 Avatar for nithishr from gravatar.com
nithishr

Unverified details

These details have not been verified by PyPI

Project links

• Documentation

• Download URL: couchbase_mcp_server-0.8.0.post1.tar.gz
• Upload date: Jun 18, 2026
• Size: 817.1 kB
• Tags: Source
• Uploaded using Trusted Publishing? Yes
• Uploaded via: twine/6.1.0 CPython/3.13.12

Hashes for couchbase_mcp_server-0.8.0.post1.tar.gz

Algorithm	Hash digest
SHA256	cdd48a7daff2667530435d7c35c1d257bbf8854d969430d2ca936602212ebaad
MD5	d14b52a0542b3dee48159b13832bf9d3
BLAKE2b-256	27a60752c64915f9ee2bd876ede2eb26888219b749aa34d3002d27fb7c96fa37

See more details on using hashes here.

• Download URL: couchbase_mcp_server-0.8.0.post1-py3-none-any.whl
• Upload date: Jun 18, 2026
• Size: 48.6 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? Yes
• Uploaded via: twine/6.1.0 CPython/3.13.12

Hashes for couchbase_mcp_server-0.8.0.post1-py3-none-any.whl

Algorithm	Hash digest
SHA256	91c929107bdeb3dae5bc2cedf4c9d956b60532c7c3bcd0661b4f7bd264ccc57d
MD5	a32df3028e4db000b99be77fb0a989a6
BLAKE2b-256	a14db62b80f859df5406cde276d627c97230117a31e6e09bbf45834b74fb3af1

See more details on using hashes here.