Environment Variables & Command Line Arguments

The MCP server can be configured using environment variables or command line arguments. If both are specified, command line arguments take priority over environment variables.

Configuration Reference

Environment Variable	CLI Argument	Description	Default
CB_CONNECTION_STRING	--connection-string	Connection string to the Couchbase cluster. See Configuring Connection String.	Required
CB_USERNAME	--username	Username for basic authentication. See Configuring Authentication.	Required (or mTLS)
CB_PASSWORD	--password	Password for basic authentication. See Configuring Authentication.	Required (or mTLS)
CB_CLIENT_CERT_PATH	--client-cert-path	Path to client certificate for mTLS. See Configuring Authentication.	Required if using mTLS
CB_CLIENT_KEY_PATH	--client-key-path	Path to client key for mTLS. See Configuring Authentication.	Required if using mTLS
CB_CA_CERT_PATH	--ca-cert-path	Path to server root certificate for TLS (self-signed / untrusted certs). Not required for Capella.
CB_MCP_READ_ONLY_MODE	--read-only-mode	Prevent all data modifications (KV and Query). See Read-Only Mode for details.	true
CB_MCP_READ_ONLY_QUERY_MODE	--read-only-query-mode	[DEPRECATED] Prevent queries that modify data. Use CB_MCP_READ_ONLY_MODE instead.	true
CB_MCP_TRANSPORT	--transport	Transport mode selection: stdio (client launches server as subprocess), http (Streamable HTTP - multiple clients, serves at /mcp), sse (deprecated - use http instead)	stdio
CB_MCP_HOST	--host	Host for HTTP/SSE transport modes	127.0.0.1
CB_MCP_PORT	--port	Port for HTTP/SSE transport modes	8000
CB_MCP_DISABLED_TOOLS	--disabled-tools	Tools to disable. See Disabling Tools	None
CB_MCP_CONFIRMATION_REQUIRED	--confirmation-required	Tools requiring user confirmation before execution. See Elicitation/Confirmation for Tool Calls	None

Checking the MCP Server Version

uvx couchbase-mcp-server --version

Configuring Authentication

For authentication, you need either:

• Username and Password (basic authentication)

  or

• Client Certificate and Key paths (mTLS authentication)

If both are specified, mTLS takes priority.

Optionally, you can specify a CA root certificate path to validate server certificates (useful for self-signed certificates).

---

Example Configurations

note

All examples below use uvx to run the server. These can be replaced with the corresponding docker run commands - see Streamable HTTP for the Docker HTTP configuration.

How to: Basic Auth

Provide a Couchbase database username and password. For Basic Authentication setup, see Manage Database Credentials (Capella) or Manage Users and Roles (self-managed).

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

How to: Connect to Capella

• Connection string: Use couchbases:// (with s) — TLS is always enabled. Find your connection string in the Capella UI under Cluster > Connect.

• TLS certificates: The bundled Capella root CA is used automatically. You do not need to set CB_CA_CERT_PATH.

• IP allowlisting: Ensure the machine running the MCP server has its IP allowed in the Capella cluster settings.

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://cb.your-capella-endpoint.cloud.couchbase.com",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

How to: Connect to Self-Managed Server with Certificates

• Connection string: Use couchbase:// for unencrypted connections or couchbases:// for TLS.

• TLS certificates: If using TLS with self-signed or untrusted certificates, set CB_CA_CERT_PATH to your CA root certificate.

• mTLS: For certificate-based authentication, use CB_CLIENT_CERT_PATH and CB_CLIENT_KEY_PATH instead of username/password.

Basic auth with custom CA:

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://your-server-hostname",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_CA_CERT_PATH": "/path/to/ca-certificate.pem"
      }
    }
  }
}

mTLS (no username/password):

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

How to: mTLS Based Auth

For environments requiring certificate-based authentication. For mTLS setup, see Configure Client Certificate Authentication.

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