Couchbase MCP Server

Couchbase MCP Server is a self-hosted MCP Server that allows AI agents to connect to and interact with data in Couchbase clusters, whether hosted on Capella or self-managed. It provides tools across categories including Cluster Health, Data Schema, Key-Value, Query, and Performance — with safety controls via read-only mode and fine-grained tool disabling. It supports both STDIO and Streamable HTTP transports.

Couchbase MCP server is distributed as a Python Package Index (PyPI) package and via Docker. Enterprise support for Couchbase MCP Server is available by licensing Couchbase AI Data Plane, which also entitles use and enterprise support of Couchbase Agent Memory and Couchbase Agent Catalog.

[][cursor-install-basic]

For full documentation, visit mcp-server.couchbase.com.

Features/Tools

Cluster setup & health tools

Data model & schema discovery tools

Document KV operations tools

Query and indexing tools

Queries are automatically scoped to the specified bucket and scope, so use collection names directly (e.g., SELECT * FROM users instead of SELECT * FROM bucket.scope.users).

CB_MCP_READ_ONLY_MODE is true by default, which means that all write operations (KV and Query) are disabled. When enabled, KV write tools are not loaded and SQL++ queries that modify data are blocked. | | explain_sql_plus_plus_query | Generate and evaluate an EXPLAIN plan for a SQL++ query. Returns query metadata, extracted plan, and plan evaluation findings. |

Query performance analysis tools

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

The MCP server can be run either from the prebuilt PyPI package or the source using uv.

Running from PyPI

We publish a pre built PyPI package for the MCP server.

Server Configuration using Pre built Package for MCP Clients

Basic Authentication

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

or

mTLS

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}

Note: If you have other MCP servers in use in the client, you can add it to the existing mcpServers object.

Running from Source

The MCP server can be run from the source using this repository.

Clone the repository to your local machine

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

Server Configuration using Source for MCP Clients

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

Note: 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.

Additional Configuration for MCP Server

The server can be configured using environment variables or command line arguments: