couchbase/mcp-server

Couchbase MCP Server

Pre-built images for the https://www.couchbase.com/ 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.

Enterprise support for Couchbase MCP Server is available by licensing https://www.couchbase.com/downloads/?family=ai-data-plane, which also entitles use and enterprise support of Couchbase Agent Memory and Couchbase Agent Catalog.

GitHub Repo: https://github.com/couchbase/mcp-server-couchbase

Dockerfile: https://github.com/couchbase/mcp-server-couchbase/blob/main/Dockerfile

Documentation: https://mcp-server.couchbase.com

Features/Tools

Cluster setup & health tools

Data model & schema discovery tools

Document KV operations tools

Query and indexing tools

Query performance analysis tools

Usage

The Docker images can be used in the supported MCP clients such as Claude Desktop, Cursor, Windsurf, etc in com***ation with Docker.

Configuration

Add the configuration specified below to the MCP configuration in your MCP client.

• Claude Desktop: https://modelcontextprotocol.io/quickstart/user
• Cursor: https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers
• Windsurf: https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin
• VS Code: https://code.visualstudio.com/docs/copilot/customization/mcp-servers
• JetBrains IDEs: https://www.jetbrains.com/help/ai-assistant/model-context-protocol.html

json
{
  "mcpServers": {
    "couchbase": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CB_CONNECTION_STRING=<couchbase_connection_string>",
        "-e",
        "CB_USERNAME=<database_username>",
        "-e",
        "CB_PASSWORD=<database_password>",
        "docker.io/couchbase/mcp-server:latest"
      ]
    }
  }
}

Environment Variables

The detailed explanation for the environment variables can be found on the https://github.com/couchbase/mcp-server-couchbase?tab=readme-ov-file#additional-configuration-for-mcp-server.

Disabling Tools

You can disable specific tools to prevent them from being loaded and exposed to the MCP client. Disabled tools will not appear in the tool discovery and cannot be invoked by the LLM.

Supported Formats

Comma-separated list:

bash
# Environment variable
CB_MCP_DISABLED_TOOLS="upsert_document_by_id, delete_document_by_id"

# Command line
uvx couchbase-mcp-server --disabled-tools upsert_document_by_id, delete_document_by_id

File path (one tool name per line):

bash
# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

# Command line
uvx couchbase-mcp-server --disabled-tools disabled_tools.txt

File format (e.g., disabled_tools.txt):

text
# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

Lines starting with # are treated as comments and ignored.

MCP Client Configuration Examples

Using comma-separated list:

json
{
  "mcpServers": {
    "couchbase": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CB_CONNECTION_STRING=couchbases://connection-string",
        "-e",
        "CB_USERNAME=username",
        "-e",
        "CB_PASSWORD=password",
        "-e",
        "CB_MCP_DISABLED_TOOLS=upsert_document_by_id,delete_document_by_id",
        "docker.io/couchbase/mcp-server:latest"
      ]
    }
  }
}

Using file path (recommended for many tools):

json
{
  "mcpServers": {
    "couchbase": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/disabled_tools.txt:/app/disabled_tools.txt",
        "-e",
        "CB_CONNECTION_STRING=couchbases://connection-string",
        "-e",
        "CB_USERNAME=username",
        "-e",
        "CB_PASSWORD=password",
        "-e",
        "CB_MCP_DISABLED_TOOLS=/app/disabled_tools.txt",
        "docker.io/couchbase/mcp-server:latest"
      ]
    }
  }
}

Important Security Note

Warning: Disabling tools alone does not guarantee that certain operations cannot be performed. The underlying database user's RBAC (Role-Based Access Control) permissions are the authoritative security control.

For example, even if you disable upsert_document_by_id and delete_document_by_id, data modifications can still occur via the run_sql_plus_plus_query tool using SQL++ DML statements (INSERT, UPDATE, DELETE, MERGE) unless:

• The CB_MCP_READ_ONLY_MODE is set to true (default), which disables all write operations (KV and Query), OR
• The database user lacks the necessary RBAC permissions for data modification

Best Practice: Always configure appropriate RBAC permissions on your Couchbase user credentials as the primary security measure. Use CB_MCP_READ_ONLY_MODE=true (the default) for comprehensive write protection, and tool disabling as an additional layer to guide LLM behavior.

Elicitation/Confirmation for Tool Calls

You can require explicit user confirmation for specific tools before execution (when the MCP client supports https://modelcontextprotocol.io/specification/2025-06-18/server/elicitation).

Configuration Formats

Comma-separated list:

bash
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"

File path (one tool name per line):

bash
CB_MCP_CONFIRMATION_REQUIRED_TOOLS=confirmation_tools.txt

File format (e.g., confirmation_tools.txt):

text
# Destructive operations
delete_document_by_id
replace_document_by_id

Lines starting with # are treated as comments and ignored.

Behavior

When a listed tool is invoked:

• If the client supports elicitation, the user is pro***ed to confirm before execution.
• If the client does not support elicitation, the tool executes without confirmation for backward compatibility.

MCP Client Configuration Example

json
{
  "mcpServers": {
    "couchbase": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CB_CONNECTION_STRING=couchbases://connection-string",
        "-e",
        "CB_USERNAME=username",
        "-e",
        "CB_PASSWORD=password",
        "-e",
        "CB_MCP_CONFIRMATION_REQUIRED_TOOLS=delete_document_by_id,replace_document_by_id",
        "docker.io/couchbase/mcp-server:latest"
      ]
    }
  }
}

Logging

The server logs to stderr by default. Logging is configured with the CB_MCP_LOG_* variables in the Environment Variables table:

• CB_MCP_LOG_LEVEL — how much is logged: info (the default) logs lifecycle events and tool invocations, debug adds verbose internal detail, and off disables all logging.
• CB_MCP_LOG_SINKS — where logs go: stderr (the default), per-level rotating files (file), or both. With file, one file is written per level (for example mcp_server.info.log and mcp_server.error.log) at the path set by CB_MCP_LOG_FILE. Mount a volume at that path to keep the logs after the container stops.

For more details, see the https://mcp-server.couchbase.com/configuration/logging.

OAuth 2.1 Authorization

When running with CB_MCP_TRANSPORT=http, the server can act as an OAuth 2.1 resource server: it validates incoming bearer JWTs against your identity provider's JWKS. It is provider-agnostic (any OAuth 2.1 / OIDC provider that publishes a JWKS — Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra, etc.) and does not issue tokens or manage users. OAuth settings are ignored on stdio.

OAuth is configured with the CB_MCP_OAUTH_* variables in the Environment Variables table:

• OAuth activates only when all three of CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER, and CB_MCP_OAUTH_JWT_AUDIENCE are set; setting only some of them fails at startup.
• Setting CB_MCP_OAUTH_MCP_BASE_URL additionally publishes RFC 9728 Protected Resource Metadata so PRM-aware clients can discover the authorization server.
• Access is gated by two scopes read from the token's scope/scp claim: couchbase-mcp:read (read tools, including SQL++) and couchbase-mcp:write (KV mutation tools). Full access requires both.

For full details, see the https://mcp-server.couchbase.com/configuration/oauth.