mcp -couchbase

This Couchbase MCP Server exposes a range of MCP-enabled tools that let a client—such as Claude Desktop, Cursor, or Windsurf Editor—interact with a Couchbase cluster over MCP. After starting the server with the uvx-based runner, connect your MCP client to the server and start issuing tools to inspect cluster health, discover data model details, and perform KV or SQL++ operations. The available capabilities include cluster configuration and health checks, bucket/scopes/collections discovery, schema discovery for collections, and various document KV operations (get, upsert, insert, replace, delete) as well as query and indexing tools for performance analysis. By default, write operations are protected by read-only mode (CB_MCP_READ_ONLY_MODE), ensuring safe interaction during exploration, with the ability to enable writes when appropriate.

To begin, run the server using the PyPI-based distribution (uvx) as shown in the configuration example, then configure your MCP client with the provided mcpServers entry. Once connected, you can use the listed tool names to drive interactions against your Couchbase cluster (for example, get_server_configuration_status, get_buckets_in_cluster, upsert_document_by_id, list_indexes, get_longest_running_queries, etc.). The tools are organized by capability: cluster health and setup, data model discovery, document KV operations, and query/performance analysis.

Prerequisites:

• Python 3.10 or higher installed on your system
• A running Couchbase cluster (Capella or self-hosted) accessible from your environment
• An MCP client (e.g., Claude Desktop, Cursor, Windsurf Editor) to connect to the MCP server

Option A: Install from PyPI and run via uvx (recommended for simple deployment)

1. Install the MCP server package:

pip install couchbase-mcp-server

2. Run the server using uvx with the prebuilt package:

uvx couchbase-mcp-server

3. Prepare the MCP client configuration (example):

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

Option B: Install from source and run from repository

1. Clone the repository:

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

2. Navigate to the repository and install dependencies (adjust as needed for your environment):

cd mcp-server-couchbase
pip install -r requirements.txt

3. Run the server from source using uv (directory path must point to the repo clone):

uv --directory /path/to/cloned/repo/mcp-server-couchbase/ run src/mcp_server.py

4. Use the same MCP client configuration as in the PyPI example to connect and issue tools.

Notes:

• If you want to enable writes, set the appropriate environment variable or configuration in the MCP client as documented by the server (e.g., CB_MCP_READ_ONLY_MODE=false as applicable in your setup).
• Ensure network connectivity between the MCP client and the Couchbase cluster, including appropriate credentials and TLS settings if using couchbases://.

Tips and common issues:

• Default read-only mode may disable KV write tools and SQL++ write queries. To enable writes for testing or production, adjust CB_MCP_READ_ONLY_MODE in the environment used by the MCP server or client configuration if supported by your deployment workflow.
• When running from source, ensure the directory path you pass to uv matches the cloned repository location and includes the trailing slash if required by your runner.
• If you encounter connectivity errors to Couchbase, verify that CB_CONNECTION_STRING is correct and that network/firewall rules allow access to the cluster endpoints.
• You can merge additional MCP servers into the same mcpServers object in your client configuration to manage multiple MCP endpoints from a single client interface.
• The tools are organized into categories (Cluster health, Data model discovery, Document KV operations, Query and indexing, and Query performance analysis). Use the exact tool names shown in the README when issuing MCP requests.