Happy slice of mcp pizzaMCP.pizza

mcp-server-couchbase

MCP.Pizza Chef: couchbase

The mcp-server-couchbase is an MCP server implementation that allows large language models to interact directly with Couchbase clusters. It supports listing scopes and collections, retrieving and upserting documents by ID, deleting documents, and running SQL++ queries in read-only mode by default. This server facilitates real-time, structured access to Couchbase data for AI workflows, requiring Python 3.10+ and a running Couchbase cluster.

Use This MCP server To

Query Couchbase collections and scopes for data retrieval Fetch specific documents by ID from Couchbase clusters Upsert documents into Couchbase collections via LLM commands Delete documents from Couchbase collections by ID Run read-only SQL++ queries on Couchbase scopes for analytics Enable LLMs to interact with Couchbase data in real time Integrate Couchbase data querying into AI-enhanced workflows

README

Couchbase MCP Server

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

Features

  • Get a list of all the scopes and collections in the specified bucket
  • Get the structure for a collection
  • Get a document by ID from a specified scope and collection
  • Upsert a document by ID to a specified scope and collection
  • Delete a document by ID from a specified scope and collection
  • Run a SQL++ query on a specified scope
    • There is an option in the MCP server, 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.

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

Clone the repository to your local machine.

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

Server Configuration for MCP Clients

This is the common configuration for the MCP clients such as Claude Desktop, Cursor, Windsurf Editor.

mcp-server-couchbase FAQ

How do I configure the mcp-server-couchbase to connect to my Couchbase cluster?
You need to provide connection details such as cluster address, bucket name, and credentials in the server configuration before starting the MCP server.
Can the mcp-server-couchbase modify data in Couchbase?
Yes, it can upsert and delete documents by ID, but SQL++ queries are read-only by default to prevent unintended data changes.
What is the READ_ONLY_QUERY_MODE in mcp-server-couchbase?
It is a setting that disables SQL++ queries that modify data or collection structure, ensuring queries are read-only by default for safety.
What versions of Python are required to run mcp-server-couchbase?
Python 3.10 or higher is required to run this MCP server.
Does mcp-server-couchbase support running SQL++ queries that change data?
By default, no. The READ_ONLY_QUERY_MODE is true by default, but it can be disabled if you want to allow data-changing queries.
Can I use mcp-server-couchbase with Couchbase Capella?
Yes, it supports connecting to Couchbase Capella clusters as well as self-hosted Couchbase clusters.
How does mcp-server-couchbase expose Couchbase data to LLMs?
It exposes scopes, collections, documents, and query results in structured formats that LLMs can consume and interact with via MCP.
Is it possible to delete documents using mcp-server-couchbase?
Yes, documents can be deleted by specifying their ID within a given scope and collection.