couchbase/mcp-server repository overview

⁠Couchbase MCP Server

Pre-built images for the 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.

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.

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

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

Documentation: https://docs.couchbase.com/mcp-server/get-started/overview.html⁠

⁠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 combination 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⁠

{
  "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 GitHub Repo⁠.

⁠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:

# 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):

# 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):

# 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:

{
  "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):

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

⁠Elicitation/Confirmation for Tool Calls

You can require explicit user confirmation for specific tools before execution (when the MCP client supports elicitation⁠).

⁠Configuration Formats

Comma-separated list:

CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"

File path (one tool name per line):

CB_MCP_CONFIRMATION_REQUIRED_TOOLS=confirmation_tools.txt

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

# 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 prompted to confirm before execution.
• If the client does not support elicitation, the tool executes without confirmation for backward compatibility.

⁠MCP Client Configuration Example

{
  "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.
• Rotation & retention — rotation size is configured in MB via CB_MCP_LOG_ROTATION_MAX_SIZE_MB (global) and per-level CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB (inheriting the global); retention via CB_MCP_LOG_RETENTION_BACKUP_COUNT (global) and per-level CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT. A rotation size of 0 is invalid and falls back to the default with a startup warning. CB_MCP_LOG_MAX_BYTES (bytes) is deprecated but still honored for backward compatibility.
• Server-config snapshot — with the file sink active, a one-shot record is written as JSON to a dedicated mcp_server_config.log.json file (derived from CB_MCP_LOG_FILE), overwritten each start, so support always has the current config even after other logs rotate.

For more details, see the documentation⁠.

⁠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 (write tools: KV mutations and index management). Full access requires both. If your IdP can't emit those canonical labels, override them with CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL.

For full details, see the documentation⁠.