CockroachDB MCP Server is a natural language interface designed for LLM and agent applications, used 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 the database.
In terms of purpose, the server exposes CockroachDB as a set of MCP tools. Requests start from any MCP client, pass through the transport layer into the security layer, and are then dispatched to one of thirteen categories of tools, ultimately reaching CockroachDB through an asyncpg connection pool.
The main capabilities are divided into thirteen categories of tools: cluster monitoring (retrieve cluster health and node status, view running queries, analyze query performance, replication and distribution status, slow queries, transaction insights, contention events, index recommendations); database operations (connect to the database, list/create/delete/switch databases, connection status and sessions, database settings); table management (create/delete/describe/rename/truncate tables, add/remove/modify columns, bulk import CSV/Avro, index and view management, schema management, list tables and relationships); query engine (execute SQL with JSON/CSV/table-format output, multi-statement transactions, explain query plans, query history); user and permission management (create, read, update, and delete users/roles/permissions, with permissions validated against an allowlist); vector search (perform similarity search using cosine/L2/inner product, manage C-SPANN ANN indexes, requires v25.2+); task management (observe and control asynchronous tasks such as BACKUP, RESTORE, IMPORT, CHANGEFEED, SCHEMA CHANGE); backup and restore (cluster/database/table-level backup and restore, supporting s3, gs, azure, nodelocal, userfile); statistics (create and display optimizer statistics); multi-region (regions, survival goals, table locality, zone configuration); change data streams (CDC pipelines to Kafka, webhook, cloud storage); cluster management (cluster settings, node decommission/drain); diagnostics (trace spans, statement diagnostics bundles).
In terms of usage, it can be started quickly via uvx (using a tagged release is recommended; the main branch is under active development and may contain breaking changes), and it also supports development installation, Docker Deployment, as well as installation as an MCPB package (Smithery / Claude Desktop). There are two configuration methods: command-line arguments or environment variables, with priority CLI arguments > environment variables > default values. Command-line options include --url, --host, --port, --db, --username, --password, --ssl-mode, --ssl-key, --ssl-cert, --ssl-ca-cert, --transport, --http-host, --http-port, --http-path, --stateless-http, --use-env, --read-only, --allow-destructive, --version. Supports stdio (default) and streamable HTTP transports. Can integrate with OpenAI Agents SDK, Augment, Claude Desktop, VS Code with GitHub Copilot, Cursor, etc.
Applicable scenarios include: enabling AI agents to query and operate CockroachDB in natural language, database monitoring and operations, vector similarity retrieval, backup and restore, CDC pipeline management, multi-region configuration, etc.
Regarding limitations and security: this server is aimed at LLM-driven agents, and prompt injection may translate into SQL injection or data corruption, so three layers of defense are built in. All database, schema, table, column, index, and view names are validated against ^[A-Za-z_][A-Za-z0-9_]{0,62}$ before being interpolated into SQL; values are always parameterized, using asyncpg placeholders; at the service-level policy, --read-only disables all DDL and write-type tools, --allow-destructive is a necessary prerequisite for drop_* tools, and each call must still pass confirm=True; the DSN is redacted in responses, and passwords will not appear in the connect() result. For production assistant-type usage, --read-only is recommended by default. Vector search requires CockroachDB v25.2+. Node decommissioning initiated via SQL only marks intent; the full lifecycle requires using the cockroach node CLI.
