Yes. mcp-cockroachdb is open source under the MIT license and free to run; you only need a CockroachDB cluster, which can be self-hosted or CockroachDB Cloud.

Is this an official Cockroach Labs server?

No. This is a community project maintained by amineelkouhen, not an official Cockroach Labs product. It connects to CockroachDB over the standard PostgreSQL wire protocol.

Can the agent modify or drop data?

Yes. The same server that reads data can create and drop tables, run transactions, and bulk-import data, so scope its database role to least privilege and treat destructive tools with care.

CockroachDB MCP server

Communityamineelkouhen10Config last verified Jun 1, 2026

A natural-language MCP server for CockroachDB: query data, manage schema, and monitor cluster health across nodes.

The CockroachDB MCP Server is a community server that gives an agent a broad, natural-language interface to CockroachDB, the distributed, PostgreSQL-compatible SQL database. It goes well beyond simple querying: the tool surface spans four areas, so an agent can run and explain SQL, manage transactions, evolve the schema, and monitor the health of a multi-node cluster. For data work it executes queries with formatting options, runs multi-statement transactions, explains query plans, and tracks query history; for schema work it creates and drops tables, views, and indexes, bulk-imports data from cloud or web storage, and analyzes table relationships.

What sets it apart is the cluster-monitoring layer built for CockroachDB's distributed nature: checking node status and replication, surfacing slow queries, contention events, transaction insights, and index recommendations. It is written in Python and runs over stdio (with an optional streamable HTTP transport for remote use), launched via uvx directly from the GitHub repository or as a Docker image. It connects with a standard PostgreSQL-style connection URL (or discrete host/port/db/user flags) and supports the full range of CockroachDB SSL modes for secure connections. Because the same tools that read data can also drop tables and import data, scope its database role to least privilege.

Quick install

Copy-paste configs are provided for all 8 supported clients. Pick your client below.

Add to ~/.claude.json

~/.claude.json

json

{
  "mcpServers": {
    "cockroachdb": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/amineelkouhen/mcp-cockroachdb.git",
        "cockroachdb-mcp-server",
        "--url",
        "postgresql://root@localhost:26257/defaultdb"
      ],
      "env": {
        "CRDB_HOST": "<CRDB_HOST>",
        "CRDB_PORT": "<CRDB_PORT>",
        "CRDB_DATABASE": "<CRDB_DATABASE>",
        "CRDB_USERNAME": "<CRDB_USERNAME>",
        "CRDB_PWD": "<CRDB_PWD>"
      }
    }
  }
}

Or via CLI

bash

claude mcp add cockroachdb -- uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --url postgresql://root@localhost:26257/defaultdb

Step-by-step guides

Available tools

Tool	Description
get_cluster_status	Reports overall cluster health and node status; optionally detailed.
show_running_queries	Lists currently running queries on a node, filterable by user and minimum duration.
get_replication_status	Shows replication status for the ranges of a given table.
get_query_insights	Returns query insights filtered by text and minimum execution time.
get_slow_queries	Surfaces slow queries above a minimum duration threshold.
get_contention_events	Lists transaction contention events, optionally filtered by table.
get_transaction_insights	Returns insights about transaction execution across the cluster.
get_index_recommendations	Provides index recommendations to improve query performance.
connect	Connects to the default CockroachDB database and creates a connection pool.
connect_database	Connects to a specified CockroachDB database with explicit host, port, user, and password.
list_databases	Lists all databases in the CockroachDB cluster.
get_connection_status	Returns the current connection status and details.
switch_database	Switches the active connection to a different database.
get_active_connections	Lists active connections or sessions to the current database.
get_database_settings	Retrieves current database or cluster settings.
create_database	Creates a new database.
drop_database	Drops an existing database.
execute_query	Executes a SQL query with optional parameters and output formatting.
execute_transaction	Runs a multi-statement transaction as a single unit.
explain_query	Returns the query plan for a statement, optionally with ANALYZE.
analyze_performance	Analyzes the performance of a query over a time range.
get_query_history	Returns recent query history with a configurable limit.
create_table	Creates a new table with specified columns and types.
bulk_import	Bulk imports data into a table from a CSV or Avro file in S3, Azure, Google Storage, or an HTTP URL.
drop_table	Drops an existing table from the database.
create_index	Creates a new index on one or more columns of a table.
drop_index	Drops an existing index.
create_view	Creates a view from a specific query.
drop_view	Drops an existing view.
list_tables	Lists all tables in the connected database, optionally scoped to a schema.
describe_table	Returns detailed schema information, column definitions, and metadata for a table.
list_views	Lists all views in a schema.
get_table_relationships	Maps relationships and foreign keys between tables.
analyze_schema	Analyzes the structure of the database schema.

Required configuration

CRDB_HOSTOptional
Hostname or address of a CockroachDB node or load balancer. Defaults to 127.0.0.1.
CRDB_PORTOptional
Port of the CockroachDB SQL interface. Defaults to 26257.
CRDB_DATABASEOptional
Database name to use as the current database. Defaults to defaultdb.
CRDB_USERNAMEOptional
SQL user that owns the client session. Defaults to root.
CRDB_PWDOptional
Password for the SQL user.
CRDB_SSL_MODEOptional
Secure connection mode: require, verify-ca, verify-full, or disable.
CRDB_SSL_CA_PATHOptional
Path to the CA certificate when SSL mode is not disable.
CRDB_SSL_CERTFILEOptional
Path to the client certificate when SSL mode is not disable.
CRDB_SSL_KEYFILEOptional
Path to the client private key when SSL mode is not disable.

What you can do with it

Diagnose a distributed cluster

Ask the agent to check get_cluster_status and get_replication_status, then use get_slow_queries, get_contention_events, and get_index_recommendations to pinpoint and explain performance problems across nodes.

Evolve schema and load data

Have the agent create tables, indexes, and views, bulk_import data from cloud storage, and analyze_schema and get_table_relationships to understand the model it is changing.

FAQ

Is it free?: Yes. mcp-cockroachdb is open source under the MIT license and free to run; you only need a CockroachDB cluster, which can be self-hosted or CockroachDB Cloud.
Is this an official Cockroach Labs server?: No. This is a community project maintained by amineelkouhen, not an official Cockroach Labs product. It connects to CockroachDB over the standard PostgreSQL wire protocol.
Can the agent modify or drop data?: Yes. The same server that reads data can create and drop tables, run transactions, and bulk-import data, so scope its database role to least privilege and treat destructive tools with care.

← Browse all databases servers