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.

CockroachDB MCP Server