{
  "markdown": "# CockroachDB Plugin for Claude Code\n\n[![Release Please](https://github.com/cockroachdb/claude-plugin/actions/workflows/release-please.yml/badge.svg)](https://github.com/cockroachdb/claude-plugin/actions/workflows/release-please.yml)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\nConnect [Claude Code](https://code.claude.com/) 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.\n\n## Installation\n\nInstall from the [Claude Marketplace](https://claude.com/plugins/cockroachdb), or in Claude Code run:\n\n```\n/install-plugin cockroachdb\n```\n\n### Local development\n\n```bash\nclaude --plugin-dir /path/to/claude-plugin\n```\n\n### Prerequisites\n\nThis plugin connects to CockroachDB via MCP (Model Context Protocol) using [MCP Toolbox for Databases](https://github.com/googleapis/mcp-toolbox) (v1.0.0+):\n\n```bash\nbrew install mcp-toolbox\n```\n\n## Configuration\n\nSet environment variables for your CockroachDB connection:\n\n```bash\nexport COCKROACHDB_HOST=\"your-cluster-host\"\nexport COCKROACHDB_PORT=\"26257\"\nexport COCKROACHDB_USER=\"your-user\"\nexport COCKROACHDB_PASSWORD=\"your-password\"\nexport COCKROACHDB_DATABASE=\"your-database\"\nexport COCKROACHDB_SSLMODE=\"verify-full\"\n```\n\nFor CockroachDB Cloud, find connection details in the [Cloud Console](https://cockroachlabs.cloud/).\n\n### Alternative MCP Backends\n\nThe plugin ships with the **MCP Toolbox** (stdio) backend active by default. To use a different backend, replace the contents of `.mcp.json`:\n\n<details>\n<summary><strong>MCP Toolbox via HTTP</strong> (remote/multi-user)</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"cockroachdb-toolbox-http\": {\n      \"type\": \"http\",\n      \"url\": \"http://your-toolbox-host:5000/mcp\"\n    }\n  }\n}\n```\n\nRun Toolbox in HTTP mode: `toolbox --config tools.yaml --address 0.0.0.0 --port 5000`\n\nRun Toolbox with the built-in web UI: `toolbox --config tools.yaml --ui --port 5000` (opens at `http://127.0.0.1:5000/ui`)\n\n> **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.\n</details>\n\n<details>\n<summary><strong>ccloud CLI</strong> (cluster lifecycle, backups, DR, networking)</summary>\n\nThe [`ccloud` CLI](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-cli-database-automation/) 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.\n\n**Install:** `brew install cockroachdb/tap/ccloud`\n\n**Authenticate (interactive):** `ccloud auth login` (opens browser; supports SSO via OIDC/SAMLv2)\n\n**Authenticate (org-scoped):** `ccloud auth login --org {organization-label}`\n\n**Authenticate (headless/CI):** `ccloud auth login --no-redirect` or use a service account API key as a bearer token.\n\n**Example agent commands:**\n```bash\n# Provision\nccloud cluster create serverless my-cluster us-east-1 --cloud AWS -o json\nccloud cluster database create my-cluster myapp -o json\n\n# Connect\nccloud cluster connection-string my-cluster --database myapp --sql-user maxroach -o json\n# Composable: pipe into jq + psql\nccloud cluster connection-string my-cluster --database myapp --sql-user maxroach -o json \\\n  | jq -r '.connection_url' | xargs -I{} psql {} -c \"SELECT count(*) FROM users\"\n\n# Operate\nccloud cluster list -o json\nccloud cluster info my-cluster -o json\nccloud cluster backup config update my-cluster --frequency 60 --retention 60\n\n# Observe\nccloud audit list --limit 10 -o json\nccloud cluster versions -o json\nccloud cluster cmek get my-cluster -o json\n\n# Scale & DR\nccloud replication create --primary-cluster prod-east --standby-cluster dr-west\nccloud cluster networking allowlist list <cluster-id> -o json\n\n# Organize\nccloud folder create Production -o json\nccloud folder contents <folder-id> -o json\n\n# Test resilience\nccloud cluster disruption set my-cluster --region us-east-1 --whole-region\n```\n\n**Coverage:** Provision, Connect, Operate, Observe, Scale & DR, Organize, Test resilience. See the [ccloud reference](https://www.cockroachlabs.com/docs/cockroachcloud/ccloud-reference) for full command list.\n</details>\n\n<details>\n<summary><strong>CockroachDB Cloud MCP Server</strong> (OAuth/API key)</summary>\n\nThe official [managed MCP server](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-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.\n\n**OAuth (recommended — opens browser for consent, scopes: `mcp:read`, `mcp:write`):**\n```json\n{\n  \"mcpServers\": {\n    \"cockroachdb-cloud\": {\n      \"type\": \"http\",\n      \"url\": \"https://cockroachlabs.cloud/mcp\",\n      \"headers\": {\n        \"mcp-cluster-id\": \"{your-cluster-id}\"\n      }\n    }\n  }\n}\n```\n\n**API Key (headless/autonomous agents):**\n```json\n{\n  \"mcpServers\": {\n    \"cockroachdb-cloud\": {\n      \"type\": \"http\",\n      \"url\": \"https://cockroachlabs.cloud/mcp\",\n      \"headers\": {\n        \"mcp-cluster-id\": \"{your-cluster-id}\",\n        \"Authorization\": \"Bearer {your-service-account-api-key}\"\n      }\n    }\n  }\n}\n```\n\nOr via CLI: `claude mcp add cockroachdb-cloud https://cockroachlabs.cloud/mcp --transport http --header \"mcp-cluster-id: {your-cluster-id}\"`\n\nSee the [quickstart guide](https://www.cockroachlabs.com/docs/cockroachcloud/connect-to-the-cockroachdb-cloud-mcp-server) for detailed setup.\n</details>\n\n## What's Included\n\n### MCP Backends\n\n| Backend                    | Status      | Transport       | Use Case                                                                                                                          |\n|----------------------------|-------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------|\n| `cockroachdb-toolbox`      | Active      | stdio           | Any CockroachDB cluster via [MCP Toolbox](https://github.com/googleapis/mcp-toolbox)                                            |\n| `cockroachdb-cloud`        | Active      | Streamable HTTP | [Managed MCP Server](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-managed-mcp-server/) — CockroachDB Cloud (OAuth/API key) |\n| `cockroachdb-toolbox-http` | Available   | SSE             | MCP Toolbox remote/multi-user via HTTP                                                                                            |\n\n### CLI Tools\n\n| Tool              | Status | Use Case                                                                                                                                           |\n|-------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------|\n| `ccloud`          | Active | [Agent-ready CLI](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-cli-database-automation/) — cluster lifecycle, backups, DR, networking, audit. Agents call directly via shell. |\n\n### Tools\n\n**MCP Toolbox** (self-hosted, any cluster):\n\n| Tool                       | Description                                      |\n|----------------------------|--------------------------------------------------|\n| `cockroachdb-execute-sql`  | Execute SQL statements (SELECT, DDL, DML)        |\n| `cockroachdb-list-schemas` | List all schemas in the database                 |\n| `cockroachdb-list-tables`  | List tables with columns, types, and constraints |\n\n**CockroachDB Cloud MCP** (managed, read tools):\n\n| Tool                    | Description                                 |\n|-------------------------|---------------------------------------------|\n| `list_clusters`         | List all accessible clusters                |\n| `get_cluster`           | Get detailed cluster information            |\n| `list_databases`        | List databases in the cluster               |\n| `list_tables`           | List tables in a database                   |\n| `get_table_schema`      | Get detailed schema for a table             |\n| `select_query`          | Execute a SELECT statement                  |\n| `explain_query`         | Execute an EXPLAIN statement                |\n| `show_running_queries`  | List currently executing queries            |\n\n**CockroachDB Cloud MCP** (managed, write tools — requires write consent):\n\n| Tool                    | Description                                 |\n|-------------------------|---------------------------------------------|\n| `create_database`       | Create a new database                       |\n| `create_table`          | Create a new table                          |\n| `insert_rows`           | Insert rows into a table                    |\n\n### Skills\n\nSkills are sourced from the [`cockroachdb-skills`](https://github.com/cockroachlabs/cockroachdb-skills) submodule via symlinks — a single source of truth shared across CockroachDB agent integrations. A [weekly CI workflow](.github/workflows/update-skills.yml) auto-detects upstream changes and opens a PR to update.\n\n| Domain                             | Examples                                                     |\n|------------------------------------|--------------------------------------------------------------|\n| **Query & Schema Design**          | cockroachdb-sql                                              |\n| **Observability & Diagnostics**    | profiling-statement-fingerprints, triaging-live-sql-activity |\n| **Security & Governance**          | auditing-cloud-cluster-security, hardening-user-privileges   |\n| **Onboarding & Migrations**        | molt-fetch, molt-verify, molt-replicator                     |\n| **Operations & Lifecycle**         | managing-cluster-capacity, upgrading-cluster-version         |\n\n### Agents\n\n| Agent                    | Description                                                                          |\n|--------------------------|--------------------------------------------------------------------------------------|\n| `cockroachdb-dba`        | CockroachDB DBA expert — performance tuning, schema review, cluster diagnostics      |\n| `cockroachdb-developer`  | Application developer expert — ORM config, retry logic, transaction patterns         |\n| `cockroachdb-operator`   | Operator/SRE expert — cluster operations, monitoring, backups, scaling, incidents    |\n\nAgents 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\").\n\n### Hooks\n\n| Hook              | Trigger               | What It Does                                                                         |\n|-------------------|-----------------------|--------------------------------------------------------------------------------------|\n| `validate-sql`    | Before SQL execution  | Blocks DROP DATABASE, TRUNCATE; warns on SERIAL, multi-DDL transactions              |\n| `check-sql-files` | After file Write/Edit | Scans SQL/code files for CockroachDB anti-patterns (SERIAL, SELECT *, missing retry) |\n\nHooks run as Python scripts (Python 3, no external dependencies) and provide automated safety guardrails.\n\n**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.\n\n## Development\n\nClone the repository:\n\n```bash\ngit clone --recurse-submodules https://github.com/cockroachdb/claude-plugin.git\ncd claude-plugin\n```\n\nTest locally:\n\n```bash\nclaude --plugin-dir .\n```\n\nValidate the plugin:\n\n```bash\nclaude plugin validate .\n```\n\n### Project Structure\n\n```\n.claude-plugin/\n  plugin.json                  # Plugin manifest with component declarations\n  marketplace.json             # Marketplace catalog for distribution\n.mcp.json                      # MCP server configuration\ntools.yaml                     # Toolbox source & tool definitions\nagents/\n  cockroachdb-dba.md           # DBA agent\n  cockroachdb-developer.md     # Developer agent\n  cockroachdb-operator.md      # Operator agent\nhooks/\n  hooks.json                   # Hook configuration\nscripts/\n  validate-sql.py              # SQL validation hook\n  check-sql-files.py           # Anti-pattern linter hook\nskills/                        # Skills copied from cockroachdb-skills submodule\nsubmodules/\n  cockroachdb-skills/          # Shared skills submodule\nassets/\n  logo.svg                     # Plugin logo\n```\n\n## Releasing\n\nThis repo uses [Release Please](https://github.com/googleapis/release-please) for automated releases.\n\n1. Use [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`) on `main`\n2. Release Please opens a Release PR with version bump and changelog\n3. Merge the Release PR to publish\n\n## Links\n\n- [CockroachDB Documentation](https://www.cockroachlabs.com/docs/)\n- [CockroachDB Cloud Console](https://cockroachlabs.cloud/)\n- [Managed MCP Server Blog Post](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-managed-mcp-server/)\n- [Cloud MCP Quickstart Guide](https://www.cockroachlabs.com/docs/cockroachcloud/connect-to-the-cockroachdb-cloud-mcp-server)\n- [ccloud CLI for AI Agents Blog Post](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-cli-database-automation/)\n- [Claude Code Plugin Docs](https://code.claude.com/docs/en/plugins)\n- [Plugin Marketplace Docs](https://code.claude.com/docs/en/plugin-marketplaces)\n- [ccloud CLI](https://www.cockroachlabs.com/docs/cockroachcloud/ccloud-get-started)\n- [MCP Toolbox for Databases](https://github.com/googleapis/mcp-toolbox)\n- [Report Issues](https://github.com/cockroachdb/claude-plugin/issues)\n\n## License\n\n[Apache-2.0](LICENSE)\n",
  "bytes": 14733,
  "sha": "e5fb3e2dd294c6279699f94414f69ecb2098a2145416ffab6fc5603ef7c801bb",
  "repo_slug": "cockroachdb/claude-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_cockroachdb_claude_plugin_cockroachdb_b4c6f836/readme"
}