Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CockroachDB MCP Server show me the top 10 customers by total purchases"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server for CockroachDB clusters. Enables AI assistants like Claude to query and interact with CockroachDB through natural language.
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
Related MCP server: CockroachDB MCP Server
pip install cockroachdb-mcpEdit 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"
}
}
}
}Quit and reopen Claude Desktop. You'll see a hammer icon indicating tools are available.
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?"
Guide | Description |
Complete installation guide | |
All configuration options | |
Detailed tool documentation | |
Common usage patterns | |
Claude.ai integration with SSO |
Tool | Description |
| Connect to the cluster |
| Close connections |
| Get cluster health |
| List cluster nodes |
Tool | Description |
| List all databases |
| List tables and views |
| Get column information |
Tool | Description |
| Run SELECT queries |
| Check query safety |
Tool | Description |
| Read rows by key or filter |
| Insert a new row |
| Update existing row |
| Delete row by key |
Tool | Description |
| Start transaction |
| Commit changes |
| Rollback changes |
Tool | Description |
| Export to JSON |
| Export to CSV |
| Save learned info |
| Retrieve knowledge |
Variable | Description |
| CockroachDB host |
| Database username |
| Database name |
Variable | Default | Description |
|
| Database port |
| Database password | |
| Cloud cluster ID | |
|
| SSL mode |
Variable | Default | Description |
|
| Block write operations |
|
| Max rows per query |
|
| Commands to block |
cockroachdb-mcpcockroachdb-mcp --http --host 0.0.0.0 --port 8080cockroachdb-mcp --streamable-http --host 0.0.0.0 --port 8080# 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/Passwords and credentials are never logged
Configurable command blocklist
Optional read-only mode
Result size limits
Query validation
SSL/TLS encryption support
Apache-2.0. See LICENSE for details.
Begin a database transaction.
Returns:
Transaction status.
Inputs: no named parameters. Returns: object
Cancel a running query.
Args:
query_id: The query ID to cancel.
Returns:
Cancellation result.
Inputs: query_id (required). Returns: object
Get the health status of the CockroachDB cluster.
Returns:
Cluster health including node count and live nodes.
Inputs: no named parameters. Returns: object
Commit the current transaction.
Returns:
Commit status.
Inputs: no named parameters. Returns: object
Connect to the CockroachDB cluster.
Uses configuration from environment variables (CRDB_HOST, CRDB_USER, etc.).
Returns:
Connection status and cluster information.
Inputs: no named parameters. Returns: object
Delete a row by primary key.
Args:
table: Table name (schema.table or just table).
id_value: Primary key value.
id_column: Name of the ID column (default: 'id').
Returns:
Delete result.
Inputs: table (required), id_value (required), id_column. Returns: object
Get detailed column information for a table.
Args:
table: Table name (schema.table or just table for public schema).
Returns:
Table structure with columns, indexes, and primary key.
Inputs: table (required). Returns: object
Disconnect from the CockroachDB cluster.
Returns:
Disconnection status.
Inputs: no named parameters. Returns: object
Execute a SQL query.
Args:
sql: SQL statement to execute.
max_rows: Maximum rows to return (default: from config).
Returns:
Query results with columns and rows.
Inputs: sql (required), max_rows. Returns: object
Get the execution plan for a query.
Args:
sql: SQL query to explain.
analyze: If True, actually execute to get runtime stats.
Returns:
Query execution plan.
Inputs: sql (required), analyze. Returns: object
Get foreign key constraints for a table.
Args:
table: Table name (schema.table or just table).
Returns:
Foreign key information.
Inputs: table (required). Returns: object
Get statistics for a table.
Args:
table: Table name (schema.table or just table).
Returns:
Table statistics including row count and size.
Inputs: table (required). Returns: object
Insert a new row into a table.
Args:
table: Table name (schema.table or just table).
data: Column names and values to insert.
returning: Columns to return from inserted row.
Returns:
Insert result.
Inputs: table (required), data (required), returning. Returns: object
List all databases in the cluster.
Args:
include_system: Include system databases (postgres, defaultdb, etc.).
Returns:
List of databases.
Inputs: include_system. Returns: object
List all nodes in the CockroachDB cluster.
Returns:
List of cluster nodes with their status.
Inputs: no named parameters. Returns: object
List schemas in the current database.
Returns:
List of schemas.
Inputs: no named parameters. Returns: object
List all tables in the database.
Args:
schema: Filter by schema name (default: all user schemas).
include_views: Include views in results.
include_system: Include system tables.
Returns:
List of tables with schema, name, and type.
Inputs: schema, include_views, include_system. Returns: object
Get detailed status for a node.
Args:
node_id: Specific node ID (optional, returns all if not specified).
Returns:
Node status information.
Inputs: node_id. Returns: object
Read rows from a table.
Args:
table: Table name (schema.table or just table).
id_value: Primary key value for single row lookup.
id_column: Name of the ID column (default: 'id').
where: WHERE clause (without 'WHERE').
columns: List of columns to return (default: all).
order_by: ORDER BY clause (without 'ORDER BY').
limit: Maximum rows to return.
Returns:
Query results.
Inputs: table (required), id_value, id_column, where, +3 more. Returns: object
Rollback the current transaction.
Returns:
Rollback status.
Inputs: no named parameters. Returns: object
Show background jobs in the cluster.
Args:
job_type: Filter by job type (BACKUP, RESTORE, IMPORT, etc.).
status: Filter by status (running, succeeded, failed, etc.).
limit: Maximum jobs to return.
Returns:
List of jobs.
Inputs: job_type, status, limit. Returns: object
Show range distribution in the cluster.
Args:
table: Optional table to filter ranges.
limit: Maximum ranges to return.
Returns:
Range distribution information.
Inputs: table, limit. Returns: object
Show database regions for multi-region clusters.
Returns:
Region information.
Inputs: no named parameters. Returns: object
Show active sessions in the cluster.
Args:
active_only: Only show sessions with active queries.
Returns:
List of sessions.
Inputs: active_only. Returns: object
Show active statements in the cluster.
Args:
limit: Maximum statements to return.
Returns:
List of active statements.
Inputs: limit. Returns: object
Show zone configurations.
Args:
table: Optional table to get zone config for.
Returns:
Zone configuration.
Inputs: table. Returns: object
Switch the active database context.
Args:
database_name: Database to switch to.
Returns:
Switch status.
Inputs: database_name (required). Returns: object
Update an existing row by primary key.
Args:
table: Table name (schema.table or just table).
id_value: Primary key value.
data: Column names and new values.
id_column: Name of the ID column (default: 'id').
returning: Columns to return from updated row.
Returns:
Update result.
Inputs: table (required), id_value (required), data (required), id_column, +1 more. Returns: object
Insert or update a row (UPSERT).
Args:
table: Table name (schema.table or just table).
data: Column names and values.
conflict_columns: Columns to check for conflicts (usually primary key).
update_columns: Columns to update on conflict (default: all except conflict columns).
returning: Columns to return.
Returns:
Upsert result.
Inputs: table (required), data (required), conflict_columns (required), update_columns, +1 more. Returns: object
Check if a query is safe to execute without running it.
Args:
sql: SQL statement to validate.
Returns:
Validation result with any issues found.
Inputs: sql (required). Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 30 tools
Each tool has a distinct purpose with clear boundaries. For example, execute_query runs queries while explain_query provides plans, and read_rows is for table reads versus list_tables for metadata. No tools appear to overlap in functionality, making selection straightforward.
All tools follow a consistent verb_noun naming pattern (e.g., begin_transaction, cancel_query, cluster_status). The naming is uniformly snake_case and uses clear, descriptive verbs that align with database operations, ensuring predictability across the set.
With 30 tools, the count is on the higher side but reasonable for a comprehensive database server covering connections, queries, transactions, metadata, and cluster management. It feels slightly heavy but each tool serves a specific role in the domain without obvious redundancy.
The toolset provides complete coverage for CockroachDB operations, including connection management, CRUD operations (insert_row, read_rows, update_row, delete_row, upsert_row), transactions, query execution and analysis, metadata inspection, and cluster monitoring. No significant gaps are apparent for typical database workflows.
Query, explore, and manage your databases through natural conversation.
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Your Supabase account in natural language: run SQL, apply migrations, manage tables, storage, edge f
