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 the CockroachDB marketplace
Add the marketplace and install the plugin:
/plugin marketplace add cockroachdb/claude-plugin
/plugin install cockroachdb@cockroachdb-claude-plugin
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 (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"
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:
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, networking)
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.
CockroachDB Cloud MCP Server (OAuth/API key)
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}"
}
}
}
}