Couchbase

You can use the Couchbase MCP Server to enable language models to directly interact with Couchbase clusters. This MCP server exposes a set of endpoints and tools that let you enumerate buckets, scopes, collections, documents, and indexes; run SQL++ queries; manage data through CRUD operations; and analyze performance and health across your Couchbase deployment.

How to use

You will connect an MCP client to the Couchbase MCP Server and begin issuing natural language prompts that the server translates into Couchbase operations. Start by choosing a transport that fits your workflow. You can use a standard STDIO configuration for a local server, or an HTTP transport mode to share a single server instance with multiple clients. Typical capabilities include retrieving bucket lists, listing scopes and collections, fetching documents by ID, upserting and deleting documents, executing SQL++ queries, and inspecting cluster health and performance.

How to install

Follow these concrete steps to install and run the Couchbase MCP Server. Prerequisites include Python 3.10 or higher, a running Couchbase cluster, and an MCP client to connect to the server.

# Prerequisites
# 1) Install Python 3.10 or higher
# 2) Ensure a Couchbase cluster is accessible (Capella or self-hosted)
# 3) Install and prepare an MCP client (Claude Desktop, Cursor, Windsurf Editor, etc.)

# Option A: Run from PyPI with a prebuilt package
uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-query-mode=true \
  --transport=stdio

# Option B: Run from source
uv <directory> run src/mcp_server.py \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-query-mode=true

Additional configuration and usage notes

The server supports multiple configuration methods, including environment variables and command line arguments. Use the provided environment variables to securely supply credentials and connection details. You can also run the server in a streamable HTTP transport mode to allow multiple clients to connect through a single server instance. If you use a local development setup, ensure you specify the correct paths to your cloned repository when running from source.

How to configure transport modes and endpoints

HTTP transport mode allows multiple clients to connect to the same MCP server instance over HTTP. The server is typically reachable at the following URL when running with HTTP transport.

# Run in HTTP transport mode
uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-query-mode=true \
  --transport=http

# MCP client configuration example
{
  "mcpServers": {
    "couchbase-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Security and access considerations

Use the required credentials to access the Couchbase cluster. You can choose basic authentication or mTLS by supplying the appropriate environment variables. If you enable mTLS, provide the client certificate and key paths. You can also supply a CA certificate path if you are connecting to a server with a self-signed certificate.

Troubleshooting tips

Verify that your Couchbase connection string, username, and password are correct. Ensure the MCP server process has the necessary environment variables set and is reachable from your MCP client. Check the server logs for any authentication or connection errors and verify that the uv/uvx command is available in your environment.

Notes on testing and usage

Integration tests can export demo cluster credentials and run a suite of tests to verify that the MCP server exposes the expected tools and can interact with a demo Couchbase cluster.

Docker image and containerization

The MCP server can be run inside a Docker container using the same environment variables for Couchbase configuration. Build and run images as described in the building and running sections, ensuring the container exposes the correct port when using HTTP transport.

Available tools

List buckets

Retrieve a list of all buckets in the Couchbase cluster.

List scopes and collections

Get all scopes and their collections in a specified bucket.

List scopes

Get all scopes within a specified bucket.

List collections in scope

Get all collections in a specific scope and bucket; requires Query service on the cluster.

Collection structure

Obtain the structure for a given collection.

Document by ID

Fetch a document by ID from a specified scope and collection.

Upsert document

Upsert (insert or update) a document by ID into a specific scope and collection.

Delete document

Delete a document by ID from a specified scope and collection.

SQL++ queries

Run a SQL++ query scoped to the chosen bucket and scope; by default, queries are read-only. The read-only mode can be overridden.

Server status

Get the current status of the MCP server.

Credentials check

Check cluster credentials by attempting a connection to the cluster.

Index listing

List all indexes in the cluster with options to filter by bucket, scope, collection, and index name.

Index recommendations

Get index recommendations for a given SQL++ query using the Couchbase Index Advisor.

Cluster health

Get cluster health status and a list of running services.

Performance analysis

Analyze query performance with metrics like longest running queries, most frequent queries, large result sets, and non-selective index usage.