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
pip install cockroachdb-mcp
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
{
"mcpServers": {
"cockroachdb": {
"command": "cockroachdb-mcp",
"env": {
"CRDB_HOST": "your-cluster.cockroachlabs.cloud",
"CRDB_USER": "your-username",
"CRDB_PASSWORD": "your-password",
"CRDB_DATABASE": "your-database",
"CRDB_CLUSTER": "your-cluster-id",
"CRDB_READ_ONLY": "true"
}
}
}
}
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 |
|---|---|
| Installation | Complete installation guide |
| Configuration | All configuration options |
| Tools Reference | Detailed tool documentation |
| Usage Examples | Common usage patterns |
| OAuth Setup | Claude.ai integration with SSO |
Available Tools
Connection & Cluster
| Tool | Description |
|---|---|
connect | Connect to the cluster |
disconnect | Close connections |
cluster_status | Get cluster health |
list_nodes | List cluster nodes |
Schema Discovery
| Tool | Description |
|---|---|
list_databases | List all databases |
list_tables | List tables and views |
describe_table | Get column information |
Query Execution
| Tool | Description |
|---|---|
execute_query | Run SELECT queries |
validate_query | Check query safety |
CRUD Operations
| Tool | Description |
|---|---|
read_rows | Read rows by key or filter |
insert_row | Insert a new row |
update_row | Update existing row |
delete_row | Delete row by key |
Transactions
| Tool | Description |
|---|---|
begin_transaction | Start transaction |
commit_transaction | Commit changes |
rollback_transaction | Rollback changes |
Export & Knowledge
| Tool | Description |
|---|---|
export_to_json | Export to JSON |
export_to_csv | Export to CSV |
save_knowledge | Save learned info |
get_all_knowledge | Retrieve knowledge |
Configuration
Required Variables
| Variable | Description |
|---|---|
CRDB_HOST | CockroachDB host |
CRDB_USER | Database username |
CRDB_DATABASE | Database name |
Optional Variables
| Variable | Default | Description |
|---|---|---|
CRDB_PORT | 26257 | Database port |
CRDB_PASSWORD | Database password | |
CRDB_CLUSTER | Cloud cluster ID | |
CRDB_SSLMODE | require | SSL mode |
Safety Settings
| Variable | Default | Description |
|---|---|---|
CRDB_READ_ONLY | false | Block write operations |
CRDB_MAX_ROWS | 1000 | Max rows per query |
CRDB_BLOCKED_COMMANDS | DROP,... | Commands to block |
Deployment Modes
Local (Default)
cockroachdb-mcp
HTTP/SSE Server
cockroachdb-mcp --http --host 0.0.0.0 --port 8080
Streamable HTTP (Claude.ai)
cockroachdb-mcp --streamable-http --host 0.0.0.0 --port 8080
Development
# Clone repository
git clone https://github.com/bpamiri/cockroachdb-mcp.git
cd cockroachdb-mcp
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Lint and format
ruff check .
ruff format .
# Type check
mypy src/
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.