CockroachDB Plugin for Claude Code

The CockroachDB plugin for Claude Code gives your AI coding agent direct access to CockroachDB databases — explore schemas, write optimized SQL, debug queries, and manage distributed clusters.

Installation

From a marketplace:

claude plugin install cockroachdb

Or load locally during development:

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

Prerequisites

This plugin connects to CockroachDB via MCP (Model Context Protocol). For the MCP Toolbox backend, install MCP Toolbox for Databases (v0.27.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"

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

Alternative MCP Backends

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

MCP Toolbox via HTTP (remote/multi-user)

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

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

ccloud CLI (cluster lifecycle, backups, DR) — Coming soon

{
  "mcpServers": {
    "ccloud": {
      "command": "ccloud",
      "args": ["mcp"],
      "env": {
        "CCLOUD_API_KEY": "${CCLOUD_API_KEY}"
      }
    }
  }
}

Requires ccloud CLI.

CockroachDB Cloud MCP Server (OAuth/API key) — Coming soon

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

What's Included

MCP Backends

Backend	Status	Transport	Use Case
cockroachdb-toolbox	Available	stdio	Any CockroachDB cluster via MCP Toolbox
cockroachdb-toolbox-http	Available	Streamable HTTP	Same as above, remote/multi-user via HTTP
ccloud	Coming soon	stdio	Cluster lifecycle, backups, DR, networking via ccloud CLI
cockroachdb-cloud	Coming soon	HTTP	CockroachDB Cloud MCP Server (OAuth/API key)

Tools

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

Skills

22 skills from cockroachdb-skills across 10 operational domains:

Domain	Skills	Examples
Query & Schema Design	1	cockroachdb-sql
Observability & Diagnostics	7	profiling-statement-fingerprints, triaging-live-sql-activity
Security & Governance	11	auditing-cloud-cluster-security, hardening-user-privileges
Onboarding & Migrations	3	molt-fetch, molt-verify, molt-replicator
Application Development	--	(planned)
Performance & Scaling	--	(planned)
Operations & Lifecycle	--	(planned)
Cost & Usage Management	--	(planned)
Integrations & Ecosystem	--	(planned)
Resilience & Disaster Recovery	--	(planned)

Skills are sourced from the cockroachdb-skills submodule via symlink — a single source of truth shared across CockroachDB agent integrations.

Agent

Agent	Description
cockroachdb-dba	CockroachDB DBA expert — performance tuning, schema review, cluster diagnostics

Invoke via /cockroachdb:cockroachdb-dba or let Claude invoke it automatically when the task involves database administration.

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 are a Claude Code-specific feature that provides automated guardrails. They run as Python scripts (no external dependencies beyond Python 3) and can block dangerous operations or surface warnings to the agent.

Development

Clone the repository:

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

Test locally:

claude --plugin-dir .

Project Structure

.claude-plugin/plugin.json    # Plugin manifest
.mcp.json                     # MCP server definitions
tools.yaml                    # Toolbox source & tool configuration
skills -> submodules/...      # Symlink to cockroachdb-skills (22 skills)
agents/cockroachdb-dba.md     # DBA agent definition
hooks/hooks.json              # Hook configuration
scripts/                      # Hook scripts (Python 3, no external deps)
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

Links

• CockroachDB Documentation
• CockroachDB Cloud Console
• Claude Code Plugin Docs
• ccloud CLI
• MCP Toolbox for Databases
• Report Issues

License

Apache-2.0