Skip to main content

Quick Start

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.

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

  1. Open the Claude Desktop configuration file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

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

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

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

tip

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

Step 2: Set Your Connection String​

The connection string format depends on your deployment type.

Use couchbases:// (with s for TLS):

couchbases://cb.your-endpoint.cloud.couchbase.com

Find your connection string in the Capella UI under Cluster > Connect.

important

Ensure the machine running the MCP server has its IP allowed in your Capella cluster settings.

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 Database Credentials (Capella) or Manage Users and Roles (self-managed).

Set CB_USERNAME and CB_PASSWORD in your MCP client configuration:

{
  "env": {
    "CB_CONNECTION_STRING": "couchbases://your-connection-string",
    "CB_USERNAME": "your-username",
    "CB_PASSWORD": "your-password"
  }
}

mTLS (Mutual TLS)​

Set CB_CLIENT_CERT_PATH and CB_CLIENT_KEY_PATH:

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

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 is the status of the Couchbase MCP server?"

The assistant will call get_server_configuration_status and return 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 above in each client tab).

Check cluster health and services

"Check the health of my Couchbase cluster and list all running services."

The assistant will call get_cluster_health_and_services, which connects to the cluster and returns the cluster health status along with all running services (Data, Query, Index, Search, etc.).

If the connection fails, verify your CB_CONNECTION_STRING, CB_USERNAME, and CB_PASSWORD values.

Try sample queries

Once connected, try these prompts:

  • "List all buckets in my cluster"
  • "Show me the scopes and collections in the travel-sample bucket"
  • "What does a document in the airline collection look like?"
  • "Find all airlines based in the United States"
  • "Run a query: SELECT COUNT(*) FROM airline"
  • "What are the longest running queries on my cluster?"
  • "Check my cluster health"

Read Only Mode​

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

  • All KV write tools (upsert, insert, replace, delete) are not loaded

  • SQL++ queries that modify data are not loaded

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

Next Steps​