Cockroachdb

CockroachDB Plugin for Claude Code

Connect Claude Code directly to your CockroachDB clusters for hands-on database work — explore schemas, write optimized SQL, debug queries, and manage distributed database clusters. This plugin provides tools across MCP backends (self-hosted MCP Toolbox and managed CockroachDB Cloud MCP Server), specialized agents (DBA, Developer, Operator), skills across operational domains, and built-in safety hooks.

Installation

Install from the Claude Marketplace, or in Claude Code run:

/install-plugin cockroachdb

Local development

claude --plugin-dir /path/to/claude-plugin

Prerequisites

This plugin connects to CockroachDB via MCP (Model Context Protocol) using MCP Toolbox for Databases (v1.0.0+):

brew install mcp-toolbox

Configuration

Set environment variables for your CockroachDB connection:

export COCKROACHDB_HOST="your-cluster-host"
export COCKROACHDB_PORT="26257"
export COCKROACHDB_USER="your-user"
export COCKROACHDB_PASSWORD="your-password"
export COCKROACHDB_DATABASE="your-database"
export COCKROACHDB_SSLMODE="verify-full"

For CockroachDB Cloud, find connection details in the Cloud Console.

Alternative MCP Backends

The plugin ships with the MCP Toolbox (stdio) backend active by default. To use a different backend, replace the contents of .mcp.json:

{
  "mcpServers": {
    "cockroachdb-toolbox-http": {
      "type": "http",
      "url": "http://your-toolbox-host:5000/mcp"
    }
  }
}

Run Toolbox in HTTP mode: toolbox --config tools.yaml --address 0.0.0.0 --port 5000

Run Toolbox with the built-in web UI: toolbox --config tools.yaml --ui --port 5000 (opens at http://127.0.0.1:5000/ui)

Note: Toolbox must successfully connect to CockroachDB on startup. If the database is unreachable (wrong host/port, env vars not set), the server will hang during initialization and the UI will be stuck on "Fetching tools...". Make sure your COCKROACHDB_* environment variables are set and the database is accessible before starting.

The ccloud CLI is an agent-ready command-line tool for full cluster lifecycle management. AI agents call ccloud directly via shell commands (not MCP protocol) -- every command supports -o json for structured output.

Install: brew install cockroachdb/tap/ccloud

Authenticate (interactive): ccloud auth login (opens browser; supports SSO via OIDC/SAMLv2)

Authenticate (org-scoped): ccloud auth login --org {organization-label}

Authenticate (headless/CI): ccloud auth login --no-redirect or use a service account API key as a bearer token.

Example agent commands:

# Provision
ccloud cluster create serverless my-cluster us-east-1 --cloud AWS -o json
ccloud cluster database create my-cluster myapp -o json

# Connect
ccloud cluster connection-string my-cluster --database myapp --sql-user maxroach -o json
# Composable: pipe into jq + psql
ccloud cluster connection-string my-cluster --database myapp --sql-user maxroach -o json \
  | jq -r '.connection_url' | xargs -I{} psql {} -c "SELECT count(*) FROM users"

# Operate
ccloud cluster list -o json
ccloud cluster info my-cluster -o json
ccloud cluster backup config update my-cluster --frequency 60 --retention 60

# Observe
ccloud audit list --limit 10 -o json
ccloud cluster versions -o json
ccloud cluster cmek get my-cluster -o json

# Scale & DR
ccloud replication create --primary-cluster prod-east --standby-cluster dr-west
ccloud cluster networking allowlist list <cluster-id> -o json

# Organize
ccloud folder create Production -o json
ccloud folder contents <folder-id> -o json

# Test resilience
ccloud cluster disruption set my-cluster --region us-east-1 --whole-region

Coverage: Provision, Connect, Operate, Observe, Scale & DR, Organize, Test resilience. See the ccloud reference for full command list.

The official managed MCP server is hosted by Cockroach Labs and requires no infrastructure setup. Authenticate via OAuth 2.1 (PKCE) or a service account API key. Read-only by default; write access requires explicit consent.

OAuth (recommended — opens browser for consent, scopes: mcp:read, mcp:write):

{
  "mcpServers": {
    "cockroachdb-cloud": {
      "type": "http",
      "url": "https://cockroachlabs.cloud/mcp",
      "headers": {
        "mcp-cluster-id": "{your-cluster-id}"
      }
    }
  }
}

API Key (headless/autonomous agents):

{
  "mcpServers": {
    "cockroachdb-cloud": {
      "type": "http",
      "url": "https://cockroachlabs.cloud/mcp",
      "headers": {
        "mcp-cluster-id": "{your-cluster-id}",
        "Authorization": "Bearer {your-service-account-api-key}"
      }
    }
  }
}

Or via CLI: claude mcp add cockroachdb-cloud https://cockroachlabs.cloud/mcp --transport http --header "mcp-cluster-id: {your-cluster-id}"

See the quickstart guide for detailed setup.

What's Included

MCP Backends

CLI Tools

Tools

MCP Toolbox (self-hosted, any cluster):

CockroachDB Cloud MCP (managed, read tools):

CockroachDB Cloud MCP (managed, write tools — requires write consent):

Skills

Skills are sourced from the cockroachdb-skills submodule via symlinks — a single source of truth shared across CockroachDB agent integrations. A weekly CI workflow auto-detects upstream changes and opens a PR to update.

Agents

Agents are auto-discovered from the agents/ directory. Claude invokes them automatically based on task context, or you can reference them directly (e.g., "ask the cockroachdb-dba agent to review this schema").

Hooks

Hooks run as Python scripts (Python 3, no external dependencies) and provide automated safety guardrails.

Windows note: the hooks invoke python3, so make sure a python3 is on your PATH. The python.org installer creates python.exe and the py launcher but *

…