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

Available Tools

Connection & Cluster

Schema Discovery

Query Execution

CRUD Operations

Transactions

Export & Knowledge

Configuration

Required Variables

Optional Variables

Safety Settings

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.

Links

• PyPI Package

• GitHub Repository

• Issue Tracker

• CockroachDB Documentation

• MCP Documentation