home / mcp / couchbase mcp server
Provides an MCP server that enables LLMs to query and manipulate Couchbase clusters through a structured set of tools.
Configuration
View docs{
"mcpServers": {
"couchbase-ecosystem-mcp-server-couchbase": {
"url": "http://localhost:8000/mcp",
"headers": {
"CB_MCP_HOST": "127.0.0.1",
"CB_MCP_PORT": "8000",
"CB_PASSWORD": "p@ssw0rd",
"CB_USERNAME": "db_user",
"CB_CA_CERT_PATH": "/path/to/ca.pem",
"CB_MCP_TRANSPORT": "http",
"CB_CLIENT_KEY_PATH": "/path/to/key.pem",
"CB_CLIENT_CERT_PATH": "/path/to/cert.pem",
"CB_CONNECTION_STRING": "couchbases://cluster.example.com",
"CB_MCP_READ_ONLY_QUERY_MODE": "true"
}
}
}
}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.
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.
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=trueThe 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.
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"
}
}
}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.
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.
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.
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.
Retrieve a list of all buckets in the Couchbase cluster.
Get all scopes and their collections in a specified bucket.
Get all scopes within a specified bucket.
Get all collections in a specific scope and bucket; requires Query service on the cluster.
Obtain the structure for a given collection.
Fetch a document by ID from a specified scope and collection.
Upsert (insert or update) a document by ID into a specific scope and collection.
Delete a document by ID from a specified scope and collection.
Run a SQL++ query scoped to the chosen bucket and scope; by default, queries are read-only. The read-only mode can be overridden.
Get the current status of the MCP server.
Check cluster credentials by attempting a connection to the cluster.
List all indexes in the cluster with options to filter by bucket, scope, collection, and index name.
Get index recommendations for a given SQL++ query using the Couchbase Index Advisor.
Get cluster health status and a list of running services.
Analyze query performance with metrics like longest running queries, most frequent queries, large result sets, and non-selective index usage.