cockroachdb

CockroachDB Plugin for Claude Code

![Release Please](https://github.com/cockroachdb/claude-plugin/actions/workflows/release-please.yml) ![License](LICENSE)

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:

<details> <summary>MCP Toolbox via HTTP (remote/multi-user)</summary>

{
  "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. </details>

<details> <summary>ccloud CLI (cluster lifecycle, backups, DR, networking)</summary>

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. </details>

<details> <summary>CockroachDB Cloud MCP Server (OAuth/API key)</summary>

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. </details>

What's Included

MCP Backends

| Backend | Status | Transport | Use Case | |----------------------------|-------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------| | cockroachdb-toolbox | Active | stdio | Any CockroachDB cluster via MCP Toolbox | | cockroachdb-cloud | Active | Streamable HTTP | Managed MCP Server — CockroachDB Cloud (OAuth/API key) | | cockroachdb-toolbox-http | Available | SSE | MCP Toolbox remote/multi-user via HTTP |

CLI Tools

| Tool | Status | Use Case | |-------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------| | ccloud | Active | Agent-ready CLI — cluster lifecycle, backups, DR, networking, audit. Agents call directly via shell. |

Tools

MCP Toolbox (self-hosted, any cluster):

| Tool | Description | |----------------------------|--------------------------------------------------| | cockroachdb-execute-sql | Execute SQL statements (SELECT, DDL, DML) | | cockroachdb-list-schemas | List all schemas in the database | | cockroachdb-list-tables | List tables with columns, types, and constraints |

CockroachDB Cloud MCP (managed, read tools):

| Tool | Description | |-------------------------|---------------------------------------------| | list_clusters | List all accessible clusters | | get_cluster | Get detailed cluster information | | list_databases | List databases in the cluster | | list_tables | List tables in a database | | get_table_schema | Get detailed schema for a table | | select_query | Execute a SELECT statement | | explain_query | Execute an EXPLAIN statement | | show_running_queries | List currently executing queries |

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

| Tool | Description | |-------------------------|---------------------------------------------| | create_database | Create a new database | | create_table | Create a new table | | insert_rows | Insert rows into a table |

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.

| Domain | Examples | |------------------------------------|--------------------------------------------------------------| | Query & Schema Design | cockroachdb-sql | | Observability & Diagnostics | profiling-statement-fingerprints, triaging-live-sql-activity | | Security & Governance | auditing-cloud-cluster-security, hardening-user-privileges | | Onboarding & Migrations | molt-fetch, molt-verify, molt-replicator | | Operations & Lifecycle | managing-cluster-capacity, upgrading-cluster-version |

Agents

| Agent | Description | |--------------------------|--------------------------------------------------------------------------------------| | cockroachdb-dba | CockroachDB DBA expert — performance tuning, schema review, cluster diagnostics | | cockroachdb-developer | Application developer expert — ORM config, retry logic, transaction patterns | | cockroachdb-operator | Operator/SRE expert — cluster operations, monitoring, backups, scaling, incidents |

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

| Hook | Trigger | What It Does | |-------------------|-----------------------|--------------------------------------------------------------------------------------| | validate-sql | Before SQL execution | Blocks DROP DATABASE, TRUNCATE; warns on SERIAL, multi-DDL transactions | | check-sql-files | After file Write/Edit | Scans SQL/code files for CockroachDB anti-patterns (SERIAL, SELECT *, missing retry) |

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 not python3.exe; on those installs the hooks safely no-op (they never block editing, but the safety checks won't run). Installing Python from the Microsoft Store — or adding a python3 alias — enables them. You do not need to turn on Windows long-path support: the hooks load their scripts through the \\?\ long-path prefix, so they work no matter how deep the plugin cache path is.

Development

Clone the repository:

git clone --recurse-submodules https://github.com/cockroachdb/claude-plugin.git
cd claude-plugin

Test locally:

claude --plugin-dir .

Validate the plugin:

claude plugin validate .

Project Structure

.claude-plugin/
  plugin.json                  # Plugin manifest with component declarations
  marketplace.json             # Marketplace catalog for distribution
.mcp.json                      # MCP server configuration
tools.yaml                     # Toolbox source & tool definitions
agents/
  cockroachdb-dba.md           # DBA agent
  cockroachdb-developer.md     # Developer agent
  cockroachdb-operator.md      # Operator agent
hooks/
  hooks.json                   # Hook configuration
scripts/
  validate-sql.py              # SQL validation hook
  check-sql-files.py           # Anti-pattern linter hook
skills/                        # Skills copied from cockroachdb-skills submodule
submodules/
  cockroachdb-skills/          # Shared skills submodule
assets/
  logo.svg                     # Plugin logo

Releasing

This repo uses Release Please for automated releases.

1. Use Conventional Commits (feat:, fix:) on main 2. Release Please opens a Release PR with version bump and changelog 3. Merge the Release PR to publish

License

Apache-2.0

Summary

Install to Claude Code