Couchbase MCP Server

What does “Couchbase” MCP Server do?

The Couchbase MCP Server is an implementation of the Model Context Protocol (MCP) that enables Large Language Models (LLMs) and AI assistants to directly interact with data stored in Couchbase clusters. Acting as a middleware, this server allows seamless integration of Couchbase database operations into AI-powered development workflows. It supports tasks such as retrieving the structure of collections, accessing documents by ID, upserting or deleting documents, and executing SQL++ queries. By connecting LLMs to live Couchbase data, developers can automate database management, enhance productivity, and streamline complex data operations through natural language interfaces. The server can be configured for read-only or read-write modes and is compatible with various MCP clients like Claude Desktop, Cursor, and Windsurf.

List of Prompts

No information about prompt templates is provided in the repository.

List of Resources

No explicit resource definitions are documented in the repository files or README.

List of Tools

• Get a list of all scopes and collections: Retrieve metadata about the organization of a specified Couchbase bucket.
• Get the structure for a collection: Access structural information (schema) for a given collection.
• Get a document by ID: Fetch a document from a specified scope and collection using its unique ID.
• Upsert a document by ID: Insert or update a document in a specified scope and collection.
• Delete a document by ID: Remove a document from a specified scope and collection.
• Run a SQL++ query: Execute a read-only or (optionally) write-enabled SQL++ query against a specified scope. By default, queries that modify data are disabled for safety.

Use Cases of this MCP Server

• Database Management: Automate common database operations such as adding, updating, or deleting documents directly from AI interfaces, reducing manual overhead.
• Data Exploration: Allow developers and AI agents to quickly explore data structures, collections, and document content for analytics or debugging purposes.
• Interactive Querying: Enable natural language queries that are translated into SQL++ and executed on Couchbase, making data retrieval accessible to non-experts.
• Automated Reporting: Facilitate the generation of dynamic reports by querying and aggregating data through AI-driven workflows.
• Seamless Integration in Dev Workflows: Enhance productivity by integrating Couchbase data access into tools like Claude, Cursor, or Windsurf, streamlining context-aware coding and documentation tasks.

How to set it up

Windsurf

1. Prerequisites: Ensure Python 3.10+ and uv are installed; have access to a Couchbase cluster.
2. Clone the repository:

   git clone https://github.com/Couchbase-Ecosystem/mcp-server-couchbase.git
   

3. Edit the Windsurf MCP client configuration to include the Couchbase MCP server:

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

4. Restart Windsurf to apply changes.
5. Verify connectivity by running a test query.

Claude

1. Prerequisites: Python 3.10+, uv, Couchbase cluster access, Claude Desktop installed.
2. Clone the Couchbase MCP Server repository.
3. Locate the configuration file:
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
4. Add the server configuration as shown above to the mcpServers section.
5. Restart Claude Desktop.
6. Test by querying Couchbase data through the Claude interface.

Cursor

1. Ensure Python 3.10+, uv, and access to a Couchbase cluster.
2. Clone the repo and install dependencies if required.
3. Add the Couchbase MCP server to Cursor’s configuration:

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

4. Restart Cursor.
5. Verify by running a database operation.

Cline

1. Meet prerequisites: Python 3.10+, uv, Couchbase cluster.
2. Clone the repository locally.
3. Add the following to Cline’s MCP configuration:

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

4. Save changes and restart Cline.
5. Confirm setup by performing a database action.

Securing API Keys:
All sensitive values (e.g., CB_PASSWORD) are stored as environment variables in the configuration’s env section.
Example:

"env": {
  "CB_CONNECTION_STRING": "couchbases://connection-string",
  "CB_USERNAME": "username",
  "CB_PASSWORD": "password",
  "CB_BUCKET_NAME": "bucket_name"
}

How to use this MCP inside flows

Using MCP in FlowHunt

To integrate MCP servers into your FlowHunt workflow, start by adding the MCP component to your flow and connecting it to your AI agent:

Click on the MCP component to open the configuration panel. In the system MCP configuration section, insert your MCP server details using this JSON format:

{ “couchbase”: { “transport”: “streamable_http”, “url”: “https://yourmcpserver.example/pathtothemcp/url" } }

Once configured, the AI agent is now able to use this MCP as a tool with access to all its functions and capabilities. Remember to change “couchbase” to whatever the actual name of your MCP server is and replace the URL with your own MCP server URL.

Overview

Based on the above tables, the Couchbase MCP Server is well-documented for setup and tool exposure but lacks explicit prompt templates, resource definitions, and sampling/roots support documentation. Its utility for database tasks is clear, but it could be improved with more MCP-native features. I would rate this MCP server a 6/10 for general LLM and developer use.

MCP Score