https://github.com/cockroachdb/cursor-plugin
CockroachDB development plugin for Cursor
https://github.com/cockroachdb/cursor-plugin
cockroach-cloud cockroachdb cursor developer-tools
Last synced: 2 months ago
JSON representation
CockroachDB development plugin for Cursor
- Host: GitHub
- URL: https://github.com/cockroachdb/cursor-plugin
- Owner: cockroachdb
- License: apache-2.0
- Created: 2026-03-11T15:50:57.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-27T21:42:56.000Z (3 months ago)
- Last Synced: 2026-03-28T03:56:28.293Z (3 months ago)
- Topics: cockroach-cloud, cockroachdb, cursor, developer-tools
- Homepage:
- Size: 419 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# CockroachDB Plugin for Cursor
[](https://github.com/cockroachdb/cursor-plugin/actions/workflows/release-please.yml)
[](LICENSE)
The CockroachDB plugin for [Cursor](https://cursor.com/) gives your AI coding agent direct access to CockroachDB databases — explore schemas, write optimized SQL, debug queries, and manage distributed clusters.
## Installation
In Cursor, run:
```
/add-plugin cockroachdb
```
Or install from the [Cursor Marketplace](https://cursor.com/marketplace).
### Prerequisites
This plugin connects to CockroachDB via MCP (Model Context Protocol). Choose the backend that fits your setup — see [MCP Backends](#mcp-backends) below.
For the **MCP Toolbox** backend (available now), install [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) (v0.27.0+):
```bash
brew install mcp-toolbox
```
## Configuration
Set environment variables for your CockroachDB connection:
```bash
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](https://cockroachlabs.cloud/).
## MCP Backends
MCP Toolbox (self-hosted, any cluster) — Default
Connect to any CockroachDB cluster (Cloud, self-hosted, local) via [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox).
**Install:** `brew install mcp-toolbox` (v0.27.0+)
**Run (stdio, default):** `toolbox --tools-file tools.yaml --stdio`
**Run (HTTP):** `toolbox --tools-file tools.yaml --address 0.0.0.0:5000`
ccloud CLI (cluster lifecycle, backups, DR, networking)
The [`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.
**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:**
```bash
# 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 -o json
# Organize
ccloud folder create Production -o json
ccloud folder contents -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](https://www.cockroachlabs.com/docs/cockroachcloud/ccloud-reference) for full command list.
CockroachDB Cloud MCP Server (OAuth/API key)
The 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.
**OAuth (recommended — opens browser for consent, scopes: `mcp:read`, `mcp:write`):**
```json
{
"mcpServers": {
"cockroachdb-cloud": {
"type": "http",
"url": "https://cockroachlabs.cloud/mcp",
"headers": {
"mcp-cluster-id": "{your-cluster-id}"
}
}
}
}
```
**API Key (headless/autonomous agents):**
```json
{
"mcpServers": {
"cockroachdb-cloud": {
"type": "http",
"url": "https://cockroachlabs.cloud/mcp",
"headers": {
"mcp-cluster-id": "{your-cluster-id}",
"Authorization": "Bearer {your-service-account-api-key}"
}
}
}
}
```
See the [quickstart guide](https://www.cockroachlabs.com/docs/cockroachcloud/connect-to-the-cockroachdb-cloud-mcp-server) for detailed setup.
## What's Included
### MCP Backends
| Backend | Status | Transport | Use Case |
|----------------------------|-------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------|
| `cockroachdb-toolbox` | Active | stdio | Any CockroachDB cluster via [MCP Toolbox](https://github.com/googleapis/genai-toolbox) |
| `cockroachdb-cloud` | Active | Streamable HTTP | [Managed MCP Server](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-managed-mcp-server/) — CockroachDB Cloud (OAuth/API key) |
| `cockroachdb-toolbox-http` | Available | Streamable HTTP | MCP Toolbox remote/multi-user via HTTP |
### CLI Tools
| Tool | Status | Use Case |
|-------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| `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. |
### 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`](https://github.com/cockroachlabs/cockroachdb-skills) submodule — a single source of truth shared across CockroachDB agent integrations.
### Rules
| Rule | Applies To |
|--------------------------|-------------------------------------------------------------------|
| **SQL Patterns** | UUID primary keys, indexing, transactions, CockroachDB SQL idioms |
| **Application Patterns** | ORM configuration, retry logic, schema design, error handling |
## Development
Clone the repository:
```bash
git clone https://github.com/cockroachdb/cursor-plugin.git
cd cursor-plugin
```
### Project Structure
```
.cursor-plugin/plugin.json # Plugin manifest
skills/ # Skills from cockroachdb-skills submodule
rules/ # 4 rule sets (.mdc files)
mcp.json # MCP server definitions (Toolbox + Cloud MCP)
tools.yaml # Toolbox source & tool configuration
submodules/cockroachdb-skills # Shared skills submodule
assets/logo.svg # Plugin logo
```
## Releasing
This repo uses [Release Please](https://github.com/googleapis/release-please) for automated releases.
1. Use [Conventional Commits](https://www.conventionalcommits.org/) (`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](https://www.cockroachlabs.com/docs/)
- [CockroachDB Cloud Console](https://cockroachlabs.cloud/)
- [Managed MCP Server Blog Post](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-managed-mcp-server/)
- [Cloud MCP Quickstart Guide](https://www.cockroachlabs.com/docs/cockroachcloud/connect-to-the-cockroachdb-cloud-mcp-server)
- [ccloud CLI for AI Agents Blog Post](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-cli-database-automation/)
- [ccloud CLI Reference](https://www.cockroachlabs.com/docs/cockroachcloud/ccloud-get-started)
- [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox)
- [Report Issues](https://github.com/cockroachdb/cursor-plugin/issues)
## License
[Apache-2.0](LICENSE)