Quick Start

Get the Couchbase MCP Server running in under 5 minutes by configuring an MCP client, connection string, and authentication.

Get the Couchbase MCP Server running in under 5 minutes.

Prerequisites

Make sure you complete the prerequisites before proceeding.

Step 1: Configure Your MCP Client

Select your MCP client and add the Couchbase MCP Server configuration, using the operational-insights subcommand.

The Docker instructions in this Quick Start run the server in stdio mode, where the MCP client starts the container. To run the server in Docker over Streamable HTTP, see Streamable HTTP Transport Mode.

You can integrate the Couchbase MCP Server into Claude Desktop by following these steps:

Open the Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Couchbase MCP Server configuration. For detailed instructions, see the MCP quickstart guide.

uvx
Docker

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "https://your-oi-endpoint",
        "CB_OPERATIONAL_INSIGHTS_USERNAME": "your-username",
        "CB_OPERATIONAL_INSIGHTS_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=https://your-oi-endpoint",
        "-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=your-username",
        "-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=your-password",
        "couchbase/mcp-server", "operational-insights"
      ]
    }
  }
}

Logs: ~/Library/Logs/Claude (macOS), %APPDATA%\Claude\Logs (Windows)

You can integrate the Couchbase MCP Server into Cursor using either of the following methods.

Option 1: Add via the Cursor MCP Links

The install link uses placeholder values from the configuration examples. Update the connection string and credentials after installation.

Option 2: Manual Addition

Go to Cursor > Cursor Settings > Tools & Integrations > MCP Tools. See the Cursor MCP documentation for details.

Add the Couchbase MCP Server configuration.

You may need to add the server configuration under a parent key of mcpServers.

uvx
Docker

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "https://your-oi-endpoint",
        "CB_OPERATIONAL_INSIGHTS_USERNAME": "your-username",
        "CB_OPERATIONAL_INSIGHTS_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=https://your-oi-endpoint",
        "-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=your-username",
        "-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=your-password",
        "couchbase/mcp-server", "operational-insights"
      ]
    }
  }
}

Logs: Bottom panel > Output list > Cursor MCP

You can integrate the Couchbase MCP Server into Windsurf by following these steps:

Navigate to Command Palette > Windsurf MCP Configuration Panel or Windsurf - Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers. See the official documentation for details.
Click Add Server > Add custom server.

Add the Couchbase MCP Server configuration.

uvx
Docker

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "https://your-oi-endpoint",
        "CB_OPERATIONAL_INSIGHTS_USERNAME": "your-username",
        "CB_OPERATIONAL_INSIGHTS_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=https://your-oi-endpoint",
        "-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=your-username",
        "-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=your-password",
        "couchbase/mcp-server", "operational-insights"
      ]
    }
  }
}

Logs: Check Windsurf output panel

You can integrate the Couchbase MCP Server into VS Code using either of the following methods.

Option 1: MCP Server bundled with Couchbase VS Code Extension (Preferred)

The Couchbase VS Code Extension (v3.0.0+) bundles the MCP server out-of-the-box. It auto-prompts to start MCP server on cluster connect in stdio transport mode.

From Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Couchbase: Start MCP Server - Start the server
Couchbase: Get MCP Server Config - Inspect config JSON
Couchbase: MCP Server Settings - Customize disabled tools, elicitation for tools, read-only mode, export paths, and so on.

Quick Start: Install extension → Connect cluster → Accept prompt to start MCP Server.

Figure 1. VS Code Extension Installation

Option 2: Manual Configuration

See the VS Code MCP documentation for details.

Create a configuration file using one of two scopes:
- Workspace: Create .vscode/mcp.json in your project root. Settings apply only to that project.
- Global (User): Run MCP: Open User Configuration from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P). Settings apply to all projects. On macOS, you can find this file at ~/Library/Application Support/Code/User/mcp.json.
Add the Couchbase MCP Server configuration.

VS Code uses servers as the top-level JSON property, not mcpServers.

uvx
Docker

{
  "servers": {
    "couchbase-oi": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "https://your-oi-endpoint",
        "CB_OPERATIONAL_INSIGHTS_USERNAME": "your-username",
        "CB_OPERATIONAL_INSIGHTS_PASSWORD": "your-password"
      }
    }
  }
}

{
  "servers": {
    "couchbase-oi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=https://your-oi-endpoint",
        "-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=your-username",
        "-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=your-password",
        "couchbase/mcp-server", "operational-insights"
      ]
    }
  }
}

Logs: Command Palette > MCP: List Servers > Show Output

You can integrate the Couchbase MCP Server into JetBrains IDEs using either of the following methods.

Install the AI Assistant or Junie plug-in.
Navigate to Settings > Tools > AI Assistant (or Junie) > MCP Server.

Click "+" to add the Couchbase MCP Server configuration and click Save.

uvx
Docker

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "https://your-oi-endpoint",
        "CB_OPERATIONAL_INSIGHTS_USERNAME": "your-username",
        "CB_OPERATIONAL_INSIGHTS_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=https://your-oi-endpoint",
        "-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=your-username",
        "-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=your-password",
        "couchbase/mcp-server", "operational-insights"
      ]
    }
  }
}

Logs: Help > Show Log in Finder/Explorer > mcp > couchbase

You can integrate the Couchbase MCP Server into Factory using any of the following methods.

See the Factory AI MCP documentation for details.

Option 1: Droid CLI

Run the following command in the Droid CLI:

droid mcp add couchbase-mcp-oi 'uvx couchbase-mcp-server operational-insights' --env CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=https://your-oi-endpoint --env CB_OPERATIONAL_INSIGHTS_USERNAME=your-username --env CB_OPERATIONAL_INSIGHTS_PASSWORD=your-password --type stdio

Option 2: Configuration File

Navigate to the MCP configuration file at ~/.factory/mcp.json and add the Couchbase MCP Server configuration.

uvx
Docker

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "https://your-oi-endpoint",
        "CB_OPERATIONAL_INSIGHTS_USERNAME": "your-username",
        "CB_OPERATIONAL_INSIGHTS_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "couchbase-oi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=https://your-oi-endpoint",
        "-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=your-username",
        "-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=your-password",
        "couchbase/mcp-server", "operational-insights"
      ]
    }
  }
}

Option 3: Factory MCP Registry

To configure the Couchbase MCP server using the Factory MCP registry, type /mcp in the chat interface to launch the interactive UI. Alternatively, type /mcp in the Droid CLI to access the MCP management menu. Browse the registry for the Couchbase MCP server and add it. Once added, Factory appends the Couchbase MCP configuration template to ~/.factory/mcp.json. Update the placeholder values with your specific settings.

Logs: ~/.factory/logs/

Replace the placeholder values with your actual Operational Insights credentials. See Environment Variables for all available options.

Step 2: Set Your Connection String

The Operational Insights MCP server supports only self-managed deployments. Capella-hosted Operational Insights is not supported.

The connection string is an HTTP(S) URL to your Operational Insights cluster:

http://your-oi-host:8095
https://your-oi-host:18095

Use https:// if you enable TLS on your Operational Insights cluster.

To find your host and credentials, see the Couchbase Server Web Console: database users are under Security (Manage Users and Roles).

If your Operational Insights cluster runs on the host machine and you’re using Docker, use host.docker.internal instead of the hostname in the connection string. See the Docker networking documentation for more details.

Step 3: Set Up Authentication

Configure authentication for your MCP server. Choose one of the following methods.

Basic Authentication (Username and Password)

For Basic Authentication setup, see Manage Users and Roles (self-managed).

Set CB_OPERATIONAL_INSIGHTS_USERNAME and CB_OPERATIONAL_INSIGHTS_PASSWORD in your MCP client configuration:

{
  "env": {
    "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "https://your-oi-endpoint",
    "CB_OPERATIONAL_INSIGHTS_USERNAME": "your-username",
    "CB_OPERATIONAL_INSIGHTS_PASSWORD": "your-password"
  }
}

mTLS (Mutual TLS)

Set CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH and CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH. If your client key or PKCS#12 bundle is encrypted, also set CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD:

{
  "env": {
    "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "https://your-oi-endpoint",
    "CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
    "CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH": "/path/to/client.key"
  }
}

See Configuring Authentication for full details.

Step 4: Validate the Setup

Save your configuration and restart your MCP client.

Check server status

Ask your AI assistant:

"What’s the status of the Couchbase MCP server?"

The assistant calls get_server_configuration_status and returns the server’s configuration, including transport mode, read-only mode status, and loaded tools.

If the tool is not available, the server did not start correctly. Check the logs for your client (listed in the preceding client tabs).

Check connectivity

"List the databases in my Operational Insights cluster."

The assistant calls operational_insights_get_databases_in_cluster, which connects to the Operational Insights cluster and returns the list of databases.

If the connection fails, verify your CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING, CB_OPERATIONAL_INSIGHTS_USERNAME, and CB_OPERATIONAL_INSIGHTS_PASSWORD values.

Read Only Mode

By default, the server runs in read-only mode (CB_MCP_READ_ONLY_MODE=true):

SQL++ queries run with the server-side readonly option, so the Operational Insights cluster itself rejects data and structure modifications.
COPY … TO (export) statements are also blocked client-side.

To enable write operations, set CB_MCP_READ_ONLY_MODE=false in your configuration. See Read-Only Mode for details.

Next Steps

Review all available Tools
Explore Configuration options
Want to customize or build from source? See Build from Source
Having issues? See Troubleshooting