mcp-server-couchbase MCP Setup & Guide

{
  "id": "io.github.couchbase/mcp-server-couchbase",
  "type": "mcp-server",
  "version": "1.0.1",
  "displayName": "mcp-server-couchbase",
  "description": "Couchbase MCP Server - Enable AI agents to connect to and interact with Couchbase clusters.",
  "repository": {
    "url": "https://github.com/couchbase/mcp-server-couchbase",
    "source": "github"
  },
  "homepage": "https://mcp-server.couchbase.com/",
  "distribution": {
    "packages": [
      {
        "registryType": "pypi",
        "identifier": "couchbase-mcp-server",
        "version": "1.0.1",
        "transport": "stdio",
        "environmentVariables": [
          {
            "name": "CB_CONNECTION_STRING",
            "description": "Couchbase connection string. Required for connecting to the cluster."
          },
          {
            "name": "CB_USERNAME",
            "description": "Couchbase database username. Required for basic authentication."
          },
          {
            "name": "CB_PASSWORD",
            "description": "Couchbase database password. Required for basic authentication.",
            "isSecret": true
          },
          {
            "name": "CB_CA_CERT_PATH",
            "description": "Couchbase CA certificate path. Required for TLS authentication in non Capella clusters."
          },
          {
            "name": "CB_CLIENT_CERT_PATH",
            "description": "Couchbase client certificate path. Required for mTLS authentication."
          },
          {
            "name": "CB_CLIENT_KEY_PATH",
            "description": "Couchbase client key path. Required for mTLS authentication."
          },
          {
            "name": "CB_MCP_READ_ONLY_MODE",
            "description": "Couchbase read only mode. Set to true to allow disable write operations across both KV and query. KV write tools are not loaded and SQL++ queries that modify data are blocked. Set to false to allow data modification queries and tools."
          },
          {
            "name": "CB_MCP_TRANSPORT",
            "description": "Transport mode for the server (stdio, http or sse). Default is stdio"
          },
          {
            "name": "CB_MCP_HOST",
            "description": "Host to run the MCP server on (default: 127.0.0.1). Used only for HTTP and SSE transport modes."
          },
          {
            "name": "CB_MCP_PORT",
            "description": "Port to run the MCP server on (default: 8000). Used only for HTTP and SSE transport modes."
          },
          {
            "name": "CB_MCP_DISABLED_TOOLS",
            "description": "Tools to disable. Accepts comma-separated tool names (e.g., 'tool_1,tool_2') or a file path containing one tool name per line."
          },
          {
            "name": "CB_MCP_CONFIRMATION_REQUIRED_TOOLS",
            "description": "Comma-separated tool names that require user confirmation before execution. Also accepts a file path containing one tool name per line. Requires the MCP client to support elicitation."
          },
          {
            "name": "CB_MCP_LOG_LEVEL",
            "description": "Logging level for the MCP server. One of off, debug, info, warning, error. Use 'off' to disable logging entirely. Invalid values fall back to info. Default is info."
          },
          {
            "name": "CB_MCP_LOG_SINKS",
            "description": "Comma-separated list of log destinations. Allowed values: stderr, file. Include 'file' to write per-level log files; include 'stderr' to write to the console. Default is stderr."
          },
          {
            "name": "CB_MCP_LOG_FILE",
            "description": "Base path for the per-level log files. One rotating file is written per level (e.g. mcp_server.info.log, mcp_server.error.log). Only used when 'file' is in CB_MCP_LOG_SINKS. Default is mcp_server.log."
          },
          {
            "name": "CB_MCP_LOG_ROTATION_MAX_SIZE_MB",
            "description": "Global maximum size in MB per-level log file before it rotates, inherited by every level unless overridden by a per-level CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB. A value of 0 is invalid and falls back to the default (1 MB) with a startup warning. Default is 1 (1 MB)."
          },
          {
            "name": "CB_MCP_LOG_MAX_BYTES",
            "description": "[DEPRECATED] Global rotation size in bytes; use CB_MCP_LOG_ROTATION_MAX_SIZE_MB (MB) instead. Still honored for backward compatibility but ignored when CB_MCP_LOG_ROTATION_MAX_SIZE_MB is also set. A value of 0 is invalid and falls back to the default with a startup warning."
          },
          {
            "name": "CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB",
            "description": "Rotation size in MB for the ERROR log file. Overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for ERROR; inherits it when unset. 0 is invalid and falls back to the inherited global with a startup warning."
          },
          {
            "name": "CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB",
            "description": "Rotation size in MB for the WARNING log file. Overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for WARNING; inherits it when unset. 0 is invalid and falls back to the inherited global with a startup warning."
          },
          {
            "name": "CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB",
            "description": "Rotation size in MB for the INFO log file. Overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for INFO; inherits it when unset. 0 is invalid and falls back to the inherited global with a startup warning."
          },
          {
            "name": "CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB",
            "description": "Rotation size in MB for the DEBUG log file. Overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for DEBUG; inherits it when unset. 0 is invalid and falls back to the inherited global with a startup warning."
          },
          {
            "name": "CB_MCP_LOG_RETENTION_BACKUP_COUNT",
            "description": "Number of rotated backup files kept per-level log file, excluding the live file. Applies to every level unless overridden per level. Set to 0 to keep only the live file (still capped by the rotation size). Default is 1."
          },
          {
            "name": "CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT",
            "description": "Rotated backups kept for the ERROR log file. Overrides CB_MCP_LOG_RETENTION_BACKUP_COUNT for ERROR; inherits it when unset."
          },
          {
            "name": "CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT",
            "description": "Rotated backups kept for the WARNING log file. Overrides CB_MCP_LOG_RETENTION_BACKUP_COUNT for WARNING; inherits it when unset."
          },
          {
            "name": "CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT",
            "description": "Rotated backups kept for the INFO log file. Overrides CB_MCP_LOG_RETENTION_BACKUP_COUNT for INFO; inherits it when unset."
          },
          {
            "name": "CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT",
            "description": "Rotated backups kept for the DEBUG log file. Overrides CB_MCP_LOG_RETENTION_BACKUP_COUNT for DEBUG; inherits it when unset."
          },
          {
            "name": "CB_MCP_OAUTH_JWT_JWKS_URI",
            "description": "JWKS endpoint of the identity provider used to verify bearer JWT signatures. Required to enable OAuth, along with CB_MCP_OAUTH_JWT_ISSUER and CB_MCP_OAUTH_JWT_AUDIENCE. Only honored when CB_MCP_TRANSPORT=http."
          },
          {
            "name": "CB_MCP_OAUTH_JWT_ISSUER",
            "description": "Expected JWT 'iss' claim value. Also advertised as the authorization server in Protected Resource Metadata when CB_MCP_OAUTH_MCP_BASE_URL is set. Required to enable OAuth."
          },
          {
            "name": "CB_MCP_OAUTH_JWT_AUDIENCE",
            "description": "Expected JWT 'aud' claim value. Required to enable OAuth."
          },
          {
            "name": "CB_MCP_OAUTH_JWT_ALGORITHM",
            "description": "JWT signing algorithm. One of RS256/384/512, ES256/384/512, PS256/384/512. Default is RS256."
          },
          {
            "name": "CB_MCP_OAUTH_MCP_BASE_URL",
            "description": "Public base URL of this MCP server. When set, the server publishes RFC 9728 Protected Resource Metadata at <base_url>/.well-known/oauth-protected-resource/mcp so PRM-aware clients can discover the authorization server. Optional."
          },
          {
            "name": "CB_MCP_OAUTH_SCOPE_READ_LABEL",
            "description": "Override the OAuth scope label the server treats as 'read' access; advertised in PRM and matched against the token's scope/scp claim. Use when your IdP cannot emit the canonical form. Default is couchbase-mcp:read."
          },
          {
            "name": "CB_MCP_OAUTH_SCOPE_WRITE_LABEL",
            "description": "Override the OAuth scope label the server treats as 'write' access; same semantics as CB_MCP_OAUTH_SCOPE_READ_LABEL. Default is couchbase-mcp:write."
          }
        ]
      },
      {
        "registryType": "oci",
        "identifier": "docker.io/couchbase/mcp-server:1.0.1",
        "transport": "stdio",
        "environmentVariables": [
          {
            "name": "CB_CONNECTION_STRING",
            "description": "Couchbase connection string. Required for connecting to the cluster."
          },
          {
            "name": "CB_USERNAME",
            "description": "Couchbase database username. Required for basic authentication."
          },
          {
            "name": "CB_PASSWORD",
            "description": "Couchbase database password. Required for basic authentication.",
            "isSecret": true
          },
          {
            "name": "CB_CA_CERT_PATH",
            "description": "Couchbase CA certificate path. Required for TLS authentication in non Capella clusters."
          },
          {
            "name": "CB_CLIENT_CERT_PATH",
            "description": "Couchbase client certificate path. Required for mTLS authentication."
          },
          {
            "name": "CB_CLIENT_KEY_PATH",
            "description": "Couchbase client key path. Required for mTLS authentication."
          },
          {
            "name": "CB_MCP_READ_ONLY_MODE",
            "description": "Couchbase read only mode. Set to true to disable write operations across both KV and query. KV write tools are not loaded and SQL++ queries that modify data are blocked. Set to false to allow data modification queries and tools."
          },
          {
            "name": "CB_MCP_TRANSPORT",
            "description": "Transport mode for the server (stdio, http or sse). Default is stdio"
          },
          {
            "name": "CB_MCP_HOST",
            "description": "Host to run the MCP server on (default: 127.0.0.1). Used only for HTTP and SSE transport modes."
          },
          {
            "name": "CB_MCP_PORT",
            "description": "Port to run the MCP server on (default: 8000). Used only for HTTP and SSE transport modes."
          },
          {
            "name": "CB_MCP_DISABLED_TOOLS",
            "description": "Tools to disable. Accepts comma-separated tool names (e.g., 'tool_1,tool_2') or a file path containing one tool name per line."
          },
          {
            "name": "CB_MCP_CONFIRMATION_REQUIRED_TOOLS",
            "description": "Comma-separated tool names that require user confirmation before execution. Also accepts a file path containing one tool name per line. Requires the MCP client to support elicitation."
          },
          {
            "name": "CB_MCP_LOG_LEVEL",
            "description": "Logging level for the MCP server. One of off, debug, info, warning, error. Use 'off' to disable logging entirely. Invalid values fall back to info. Default is info."
          },
          {
            "name": "CB_MCP_LOG_SINKS",
            "description": "Comma-separated list of log destinations. Allowed values: stderr, file. Include 'file' to write per-level log files; include 'stderr' to write to the console. Default is stderr."
          },
          {
            "name": "CB_MCP_LOG_FILE",
            "description": "Base path for the per-level log files. One rotating file is written per level (e.g. mcp_server.info.log, mcp_server.error.log). Only used when 'file' is in CB_MCP_LOG_SINKS. Default is mcp_server.log."
          },
          {
            "name": "CB_MCP_LOG_ROTATION_MAX_SIZE_MB",
            "description": "Global maximum size in MB per-level log file before it rotates, inherited by every level unless overridden by a per-level CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB. A value of 0 is invalid and falls back to the default (1 MB) with a startup warning. Default is 1 (1 MB)."
          },
          {
            "name": "CB_MCP_LOG_MAX_BYTES",
            "description": "[DEPRECATED] Global rotation size in bytes; use CB_MCP_LOG_ROTATION_MAX_SIZE_MB (MB) instead. Still honored for backward compatibility but ignored when CB_MCP_LOG_ROTATION_MAX_SIZE_MB is also set. A value of 0 is invalid and falls back to the default with a startup warning."
          },
          {
            "name": "CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB",
            "description": "Rotation size in MB for the ERROR log file. Overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for ERROR; inherits it when unset. 0 is invalid and falls back to the inherited global with a startup warning."
          },
          {
            "name": "CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB",
            "description": "Rotation size in MB for the WARNING log file. Overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for WARNING; inherits it when unset. 0 is invalid and falls back to the inherited global with a startup warning."
          },
          {
            "name": "CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB",
            "description": "Rotation size in MB for the INFO log file. Overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for INFO; inherits it when unset. 0 is invalid and falls back to the inherited global with a startup warning."
          },
          {
            "name": "CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB",
            "description": "Rotation size in MB for the DEBUG log file. Overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for DEBUG; inherits it when unset. 0 is invalid and falls back to the inherited global with a startup warning."
          },
          {
            "name": "CB_MCP_LOG_RETENTION_BACKUP_COUNT",
            "description": "Number of rotated backup files kept per-level log file, excluding the live file. Applies to every level unless overridden per level. Set to 0 to keep only the live file (still capped by the rotation size). Default is 1."
          },
          {
            "name": "CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT",
            "description": "Rotated backups kept for the ERROR log file. Overrides CB_MCP_LOG_RETENTION_BACKUP_COUNT for ERROR; inherits it when unset."
          },
          {
            "name": "CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT",
            "description": "Rotated backups kept for the WARNING log file. Overrides CB_MCP_LOG_RETENTION_BACKUP_COUNT for WARNING; inherits it when unset."
          },
          {
            "name": "CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT",
            "description": "Rotated backups kept for the INFO log file. Overrides CB_MCP_LOG_RETENTION_BACKUP_COUNT for INFO; inherits it when unset."
          },
          {
            "name": "CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT",
            "description": "Rotated backups kept for the DEBUG log file. Overrides CB_MCP_LOG_RETENTION_BACKUP_COUNT for DEBUG; inherits it when unset."
          },
          {
            "name": "CB_MCP_OAUTH_JWT_JWKS_URI",
            "description": "JWKS endpoint of the identity provider used to verify bearer JWT signatures. Required to enable OAuth, along with CB_MCP_OAUTH_JWT_ISSUER and CB_MCP_OAUTH_JWT_AUDIENCE. Only honored when CB_MCP_TRANSPORT=http."
          },
          {
            "name": "CB_MCP_OAUTH_JWT_ISSUER",
            "description": "Expected JWT 'iss' claim value. Also advertised as the authorization server in Protected Resource Metadata when CB_MCP_OAUTH_MCP_BASE_URL is set. Required to enable OAuth."
          },
          {
            "name": "CB_MCP_OAUTH_JWT_AUDIENCE",
            "description": "Expected JWT 'aud' claim value. Required to enable OAuth."
          },
          {
            "name": "CB_MCP_OAUTH_JWT_ALGORITHM",
            "description": "JWT signing algorithm. One of RS256/384/512, ES256/384/512, PS256/384/512. Default is RS256."
          },
          {
            "name": "CB_MCP_OAUTH_MCP_BASE_URL",
            "description": "Public base URL of this MCP server. When set, the server publishes RFC 9728 Protected Resource Metadata at <base_url>/.well-known/oauth-protected-resource/mcp so PRM-aware clients can discover the authorization server. Optional."
          },
          {
            "name": "CB_MCP_OAUTH_SCOPE_READ_LABEL",
            "description": "Override the OAuth scope label the server treats as 'read' access; advertised in PRM and matched against the token's scope/scp claim. Use when your IdP cannot emit the canonical form. Default is couchbase-mcp:read."
          },
          {
            "name": "CB_MCP_OAUTH_SCOPE_WRITE_LABEL",
            "description": "Override the OAuth scope label the server treats as 'write' access; same semantics as CB_MCP_OAUTH_SCOPE_READ_LABEL. Default is couchbase-mcp:write."
          }
        ]
      }
    ],
    "remotes": []
  },
  "dependencies": [],
  "installTargets": [
    "claude-code",
    "claude-desktop",
    "cursor",
    "vscode",
    "trae",
    "cherry-studio",
    "lingma",
    "windsurf",
    "cline",
    "workbuddy"
  ],
  "keywords": [],
  "provenance": {
    "origin": "official-mcp-registry",
    "originalId": "io.github.couchbase/mcp-server-couchbase",
    "originalUrl": "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.couchbase%2Fmcp-server-couchbase/versions/latest",
    "isOfficial": true,
    "status": "active"
  }
}