Interact with the data stored in Couchbase clusters using natural language.
An MCP server implementation of Couchbase that allows LLMs to directly interact with Couchbase clusters.
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.Clone the repository to your local machine.
git clone https://github.com/Couchbase-Ecosystem/mcp-server-couchbase.git
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 clusterCB_USERNAME
: The username with access to the bucket to use to connectCB_PASSWORD
: The password for the username to connectCB_BUCKET_NAME
: The name of the bucket that the server will accessREAD_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.
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.
~/Library/Application Support/Claude/claude_desktop_config.json
%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.
The logs for Claude Desktop can be found in the following locations:
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.
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.
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.
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.
There is an option to run the MCP server in Server-Sent Events (SSE) transport mode.
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.
The MCP server can also be built and run as a Docker container. Prebuilt images can be found on DockerHub.
docker built -t mcp/couchbase .
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
The Couchbase MCP server can also be used as a managed server in your agentic applications via Smithery.ai.
command
field in the configuration.mcp-server-couchbase.log
.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!
Read-only database access with schema inspection
Database interaction and business intelligence capabilities
Embeddings, vector search, document storage, and full-text search with the open-source AI application database
Query your ClickHouse database server.
Provides AI assistants with a secure and structured way to explore and analyze data in GreptimeDB.
Hydrolix time-series datalake integration providing schema exploration and query capabilities to LLM-based workflows.
Open source MCP server specializing in easy, fast, and secure tools for Databases.
Interact & query with Meilisearch (Full-text & semantic search API)
Search, Query and interact with data in your Milvus Vector Database.
Query and analyze data with MotherDuck and local DuckDB