amineelkouhen/mcp-cockroachdb

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.
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).