cockroachdb-mcp
An MCP (Model Context Protocol) server for CockroachDB clusters. Enables AI assistants like Claude to query and interact with CockroachDB through natural language.
Features
Natural Language Queries: Ask Claude about your data in plain English
Schema Discovery: Explore databases, tables, columns, and indexes
CRUD Operations: Read, insert, update, and delete rows safely
Cluster Operations: Monitor cluster health and node status
Multi-Region Support: Query distributed data across regions
Data Export: Export query results to JSON or CSV
Transaction Support: Begin, commit, and rollback transactions
Knowledge Persistence: Claude remembers what it learns about your cluster
Safety Controls: Read-only mode, command blocking, row limits
Connection Watchdog: Automatic recovery from hung connections
OAuth Integration: Deploy as a Claude.ai Custom Connector with SSO
Quick Start
1. Install
2. Configure Claude Desktop
Edit your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Restart Claude Desktop
Quit and reopen Claude Desktop. You'll see a hammer icon indicating tools are available.
4. Start Chatting
Ask Claude about your CockroachDB data:
"What tables are available?"
"Describe the users table"
"Show me the top 10 orders by total amount"
"What's the cluster health status?"
Documentation
Guide | Description |
Complete installation guide | |
All configuration options | |
Detailed tool documentation | |
Common usage patterns | |
Claude.ai integration with SSO |
Available Tools
Connection & Cluster
Tool | Description |
| Connect to the cluster |
| Close connections |
| Get cluster health |
| List cluster nodes |
Schema Discovery
Tool | Description |
| List all databases |
| List tables and views |
| Get column information |
Query Execution
Tool | Description |
| Run SELECT queries |
| Check query safety |
CRUD Operations
Tool | Description |
| Read rows by key or filter |
| Insert a new row |
| Update existing row |
| Delete row by key |
Transactions
Tool | Description |
| Start transaction |
| Commit changes |
| Rollback changes |
Export & Knowledge
Tool | Description |
| Export to JSON |
| Export to CSV |
| Save learned info |
| Retrieve knowledge |
Configuration
Required Variables
Variable | Description |
| CockroachDB host |
| Database username |
| Database name |
Optional Variables
Variable | Default | Description |
|
| Database port |
| Database password | |
| Cloud cluster ID | |
|
| SSL mode |
Safety Settings
Variable | Default | Description |
|
| Block write operations |
|
| Max rows per query |
|
| Commands to block |
Deployment Modes
Local (Default)
HTTP/SSE Server
Streamable HTTP (Claude.ai)
Development
Security
Passwords and credentials are never logged
Configurable command blocklist
Optional read-only mode
Result size limits
Query validation
SSL/TLS encryption support
License
Apache-2.0. See LICENSE for details.