playbooks

home / mcp / cockroachdb mcp server

CockroachDB MCP Server

The CockroachDB MCP Server is a natural language interface designed for agentic applications to manage, monitor and query data in CockroachDB.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "amineelkouhen-mcp-cockroachdb": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/amineelkouhen/[email protected]",
        "cockroachdb-mcp-server",
        "--url",
        "postgresql://localhost:26257/defaultdb"
      ],
      "env": {
        "CRDB_PWD": "YOUR_PASSWORD",
        "CRDB_HOST": "localhost",
        "CRDB_PORT": "26257",
        "CRDB_DATABASE": "defaultdb",
        "CRDB_SSL_MODE": "disable|allow|prefer|require|verify-ca|verify-full",
        "CRDB_USERNAME": "root",
        "CRDB_SSL_CA_PATH": "PATH_TO_CA_CERT",
        "CRDB_SSL_KEYFILE": "PATH_TO_KEYFILE",
        "CRDB_SSL_CERTFILE": "PATH_TO_CERTFILE"
      }
    }
  }
}

You can interact with CockroachDB using a natural language MCP server designed to let AI agents manage, monitor, and query data directly in CockroachDB. It integrates with MCP clients to enable seamless, scalable workflows that translate natural language requests into database operations and insights.

How to use

You will run the MCP server using your preferred MCP client or development setup, then issue natural language prompts that the server translates into CockroachDB operations. Start by choosing a connection method your workflow requires: either connect through an MCP client using a standard MCP transport, or run the server locally for development and testing. Your prompts can cover cluster health, database and table management, and SQL queries with results returned in convenient formats.

How to install

Prerequisites: install Python and the required tooling for MCP workflows, or use the uvx tool for quick startup.

Additional sections

Configuration lets you control how the MCP server connects to CockroachDB and how it communicates with MCP clients. You can supply configuration via command line arguments or environment variables, with command line arguments taking precedence over environment variables.

Environment variables you may use include CRDB_HOST, CRDB_PORT, CRDB_DATABASE, CRDB_USERNAME, CRDB_PWD, CRDB_SSL_MODE, CRDB_SSL_CA_PATH, CRDB_SSL_CERTFILE, and CRDB_SSL_KEYFILE. These variables map to the CockroachDB connection and security settings and can be combined with a local development setup or a deployed instance.

Testing and debugging can be aided by the MCP Inspector to visually inspect MCP server interactions. Start the inspector with the appropriate uv run command to attach debugging capabilities to your server instance.

Metadata and MCP server configurations

The MCP server includes two explicit startup patterns you can use right away. The first is a quick start method using uvx to fetch and run from a specific release tag, connecting to CockroachDB via a SQL URI. The second starts the server through development tooling, running the main entry script directly with uv run. Use the approach that best fits your workflow.

Tools and capabilities

Cluster Monitoring: Check cluster health, node status, current queries, performance insights, replication and distribution status, and view contention events with optional table filtering.

Database Operations: Connect to CockroachDB, list/create/drop/switch databases, monitor active sessions, and retrieve database settings.

Table Management: Create, drop, and describe tables and views; bulk import data; manage indexes; list tables, views, and table relationships; and analyze schema structure.

Query Engine: Execute SQL queries with various output formats, run multi-statement transactions, explain query plans, and track query history.

Security and best practices

When connecting to CockroachDB, prefer TLS/SSL where available and ensure credentials are securely managed when using environment variables or configuration files.

License

This project is licensed under the MIT License.

Contact

If you have questions or need support, reach out via GitHub Issues.

Available tools

cluster_monitoring

Tools for monitoring and managing CockroachDB clusters, including health, node status, running queries, and performance insights.

database_operations

Handle databases: connect, list, create, drop, switch, and view settings; monitor sessions.

table_management

Manage tables, views, indexes, and schema relationships; bulk import and analyze schema.

query_engine

Execute SQL queries, run multi-statement transactions, explain plans, and track history.