CockroachDB MCP Server

Overview

The CockroachDB MCP Server is a natural language interface designed for LLMs and agentic applications to manage, monitor, and query data in CockroachDB. It integrates seamlessly with MCP (Model Content Protocol) clients, such as Claude Desktop or Cursor, enabling AI-driven workflows to interact directly with your database.

Table of Contents

• Overview
• Features
• Tools
  • Cluster Monitoring
  • Database Operations
  • Table Management
  • Query Engine
  • User & Privilege Management
  • Vector Search
  • Job Management
  • Backup & Restore
  • Statistics
  • Multi-Region
  • Changefeeds
  • Cluster Admin
  • Diagnostics
• Installation
  • Quick Start with uvx
  • Development Installation
  • With Docker
  • As an MCPB Bundle (Smithery / Claude Desktop)
• Configuration
  • Configuration via command line arguments
  • Configuration via Environment Variables
• Integrations
  • OpenAI Agents SDK
  • Augment
  • Claude Desktop
  • VS Code with GitHub Copilot
  • Cursor
• Testing
• Contributing
• License
• Quality Badge
• Contact

Features

• Natural-Language Queries: AI agents can query and transact via natural language.
• Cluster Monitoring: Cluster status, node health, replication, slow queries, contention, index recommendations.
• Database Operations: List, create, drop, and switch databases.
• Table Management: Create, drop, alter (add/drop/rename column), truncate, rename, describe; bulk-import; indexes, views, schemas.
• Query Engine: Parameterized SQL with json/csv/table output, multi-statement transactions, explain, history.
• User & Privilege Management: Provision SQL users and roles, grant/revoke privileges. Lets you run the agent under a scoped non-root user.
• Vector Search: Similarity search with cosine/L2/inner-product metrics (auto-detected from index opclass), C-SPANN ANN index management (v25.2+).
• Job Management: Observe and control async jobs (BACKUP, RESTORE, IMPORT, CHANGEFEED, SCHEMA CHANGE).
• Backup & Restore: Full / database / table backup and restore against s3, gs, azure, nodelocal, userfile.
• Statistics: Create and show optimizer statistics.
• Multi-Region: Regions, survival goals, locality (REGIONAL_BY_ROW etc.), zone configuration.
• Changefeeds: CDC pipelines to Kafka / webhook / cloud-storage with sink-scheme validation.
• Cluster Admin: Cluster settings, decommission/drain (gated).
• Diagnostics: Tracing spans, statement-diagnostics bundles.
• Safety First: Strict identifier validation, parameterized values, --read-only mode, explicit confirm=True for destructive ops, redacted DSN responses.
• Seamless MCP Integration: Works with any MCP client (Claude Desktop, Cursor, VS Code Copilot, OpenAI Agents SDK, etc.).
• Multiple Transports: stdio (default) and streamable HTTP.

Tools

The CockroachDB MCP Server exposes CockroachDB as a set of MCP tools. Requests flow from any MCP client through a transport, into the safety layer, then to one of the thirteen tool categories, and finally to CockroachDB via an asyncpg connection pool.

flowchart LR
    subgraph Clients["MCP Clients"]
        direction TB
        C1["Claude Desktop"]
        C2["Cursor"]
        C3["VS Code Copilot"]
        C4["OpenAI Agents SDK"]
        C5["Augment"]
    end

    subgraph Transport["Transport"]
        direction TB
        T1["stdio"]
        T2["streamable HTTP"]
    end

    subgraph Server["CockroachDB MCP Server (FastMCP)"]
        direction TB

        subgraph Safety["Safety Layer"]
            direction TB
            S1["Identifier validation<br/>(strict regex)"]
            S2["Parameterized values<br/>($1, $2, ...)"]
            S3["--read-only gate"]
            S4["--allow-destructive<br/>+ confirm=True"]
            S5["DSN redaction"]
        end

        subgraph Tools["Tool Categories (13)"]
            direction TB

            subgraph Obs["Observe & Diagnose"]
                O1["Cluster Monitoring"]
                O2["Diagnostics"]
                O3["Statistics"]
            end

            subgraph Data["Data & Schema"]
                D1["Database Operations"]
                D2["Table Management"]
                D3["Query Engine"]
                D4["Vector Search (C-SPANN)"]
            end

            subgraph Ops["Data Movement"]
                P1["Job Management"]
                P2["Backup & Restore"]
                P3["Changefeeds (CDC)"]
            end

            subgraph Adm["Admin & Topology"]
                A1["User & Privilege Management"]
                A2["Multi-Region"]
                A3["Cluster Admin"]
            end
        end

        Pool["asyncpg connection pool"]
    end

    DB[("CockroachDB<br/>single- or multi-region cluster")]

    Clients --> Transport
    Transport --> Safety
    Safety --> Tools
    Tools --> Pool
    Pool --> DB

The tools are organized into thirteen categories, grouped above by concern. Every write-shaped tool is gated by --read-only. Every destructive tool also requires --allow-destructive plus a per-call confirm=True parameter; see the Safety Model section.

Cluster Monitoring

Purpose: Provides tools for monitoring and managing CockroachDB clusters.

Summary:

• Get cluster health and node status.
• Show currently running queries.
• Analyze query performance statistics.
• Retrieve replication and distribution status for tables or the whole database.
• Get query execution insights with optional keyword filtering.
• Find slow queries from statement statistics with optional keyword filtering.
• Get transaction execution insights with optional keyword filtering.
• View contention events with optional table filtering.
• Get index recommendations from query insights.

Database Operations

Purpose: Handles database-level operations and connection management.

Summary:

• Connect to a CockroachDB database.
• List, create, drop, and switch databases.
• Get connection status and active sessions.
• Retrieve database settings.

Table Management

Purpose: Provides tools for managing tables, indexes, views, schemas, and relationships in CockroachDB.

Summary:

• Create, drop, describe, rename, and truncate tables (destructive ops gated).
• alter_table_add_column, alter_table_drop_column, alter_table_rename_column.
• Bulk import data into tables (CSV / Avro from s3/gs/azure/http(s)).
• Manage indexes (create/drop).
• Manage views (create/drop, list).
• Manage schemas (list_schemas, create_schema, drop_schema).
• List tables and table relationships; analyze schema structure and metadata.

Query Engine

Purpose: Executes and manages SQL queries and transactions.

Summary:

• Execute SQL queries with formatting options (JSON, CSV, table).
• Run multi-statement transactions.
• Explain query plans for optimization.
• Track and retrieve query history.

User & Privilege Management

Purpose: Manage SQL users, roles, and privileges. Use this from an administrative agent to provision the agent's own scoped (non-root) user.

Summary:

• list_users, create_user, drop_user, alter_user_password.
• create_role, drop_role, grant_role, revoke_role.
• show_grants, grant_privileges, revoke_privileges.

Privileges are validated against an allowlist (SELECT, INSERT, UPDATE, DELETE, ALL, BACKUP, RESTORE, MODIFYCLUSTERSETTING, ...). Identifiers go through the same strict regex as everywhere else.

Vector Search

Purpose: Search VECTOR columns with CockroachDB's similarity operators (v25.2+) and manage C-SPANN ANN indexes.

Summary:

• vector_similarity_search with metric of cosine (default), l2, ip, or auto (matches the existing index opclass). Returns distance and a derived similarity field.
• create_cspann_index with metric → opclass mapping (vector_cosine_ops / vector_l2_ops / vector_ip_ops).
• drop_cspann_index (destructive).

The query vector is always passed as a $1::VECTOR parameter; identifier and optional where clause values are validated. For normalized embeddings (e.g. Takara DS1, OpenAI text-embedding-3) all three metrics rank identically; the default cosine is the safest because it ignores magnitude.

Job Management

Purpose: Observe and control long-running CockroachDB jobs (BACKUP, RESTORE, IMPORT, SCHEMA CHANGE, CHANGEFEED).

Summary:

• list_jobs (filter by status and type), get_job_status.
• pause_job, resume_job, cancel_job (destructive).

Backup & Restore