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
• Installation
  • Quick Start with uvx
  • Development Installation
  • With Docker
• 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: Enables AI agents to query and create transactions using natural language, supporting complex workflows.
• Search & Filtering: Supports efficient data retrieval and searching in CockroachDB.
• Cluster Monitoring: Check and monitor the CockroachDB cluster status, including node health and replication.
• Database Operations: Perform all operations related to databases, such as creation, deletion, and configuration.
• Table Management: Handle tables, indexes, and schemas for flexible data modeling.
• Seamless MCP Integration: Works with any MCP client for smooth communication.
• Scalable & Lightweight: Designed for high-performance data operations.

Tools

The CockroachDB MCP Server Server provides tools to manage the data stored in CockroachDB.

The tools are organized into four main categories:

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, and schema relationships in CockroachDB.

Summary:

• Create, drop, and describe tables and views.
• Bulk import data into tables.
• Manage indexes (create/drop).
• List tables, views, 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.

Installation

The CockroachDB MCP Server supports the stdio transport and the streamable-http transport.

Quick Start with uvx

The easiest way to use the CockroachDB MCP Server is with uvx, which allows you to run it directly from GitHub (from a branch, or use a tagged release). It is recommended to use a tagged release. The main branch is under active development and may contain breaking changes. As an example, you can execute the following command to run the 0.1.0 release:

uvx --from git+https://github.com/amineelkouhen/[email protected] cockroachdb-mcp-server --url postgresql://localhost:26257/defaultdb

Check the release notes for the latest version in the Releases section. Additional examples are provided below.

# Run with CockroachDB URI
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --url postgresql://localhost:26257/defaultdb

# Run with individual parameters
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --host localhost --port 26257 --database defaultdb --user root --password mypassword

# See all options
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --help

# Run with streamable HTTP transport
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
  --url postgresql://localhost:26257/defaultdb \
  --transport http \
  --http-host 0.0.0.0 \
  --http-port 8000 \
  --http-path /mcp

Development Installation

For development or if you prefer to clone the repository:

# Clone the repository
git clone https://github.com/amineelkouhen/mcp-cockroachdb.git
cd mcp-cockroachdb

# Install dependencies using uv
uv venv
source .venv/bin/activate
uv sync

# Run with CLI interface
uv run cockroachdb-mcp-server --help

# Or run the main file directly (uses environment variables)
uv run src/main.py

Once you cloned the repository, installed the dependencies and verified you can run the server, you can configure Claude Desktop or any other MCP Client to use this MCP Server running the main file directly (it uses environment variables). This is usually preferred for development. The following example is for Claude Desktop, but the same applies to any other MCP Client.

1. Specify your CockroachDB credentials and TLS configuration
2. Retrieve your uv command full path (e.g. which uv)
3. Edit the claude_desktop_config.json configuration file    - on a MacOS, at ~/Library/Application Support/Claude/

{
    "mcpServers": {
        "cockroach": {
            "command": "<full_path_uv_command>",
            "args": [
                "--directory",
                "<your_mcp_server_directory>",
                "run",
                "src/main.py"
            ],
            "env": {
                "CRDB_HOST": "<your_cockroachdb_hostname>",
                "CRDB_PORT": "<your_cockroachdb_port>",
                "CRDB_DATABASE": "<your_cockroach_database>",
                "CRDB_USERNAME": "<your_cockroachdb_user>",
                "CRDB_PWD": "<your_cockroachdb_password>",
                "CRDB_SSL_MODE": "disable|allow|prefer|require|verify-ca|verify-full",
                "CRDB_SSL_CA_PATH": "<your_cockroachdb_ca_path>",
                "CRDB_SSL_KEYFILE": "<your_cockroachdb_keyfile_path>",
                "CRDB_SSL_CERTFILE": "<your_cockroachdb_certificate_path>",
            }
        }
    }
}

You can troubleshoot problems by tailing the log file.

tail -f ~/Library/Logs/Claude/mcp-server-cockroach.log

With Docker Compose (Local Development)

For local development and testing, use the provided docker-compose.yaml to spin up both CockroachDB and the MCP server:

# Start CockroachDB and MCP server
docker compose up -d

# The MCP server is available at http://localhost:8000/mcp/
# CockroachDB UI is available at http://localhost:8080

# View logs
docker compose logs -f mcp-server

# Stop and clean up
docker compose down -v

With Docker

You can use a dockerized deployment of this server. You can either build your image or use the official CockroachDB MCP Docker image.

If you'd like to build your image, the CockroachDB MCP Server provides a Dockerfile. Build this server's image with:

docker build -t mcp-cockroachdb .

Finally, configure the client to create the container at start-up. An example for Claude Desktop is provided below. Edit the claude_desktop_config.json and add:

{
  "mcpServers": {
    "cockroach": {
      "command": "docker",
      "args": ["run",
                "--rm",
                "--name",
                "cockroachdb-mcp-server",
                "-e", "CRDB_HOST=<cockroachdb_host>",
                "-e", "CRDB_PORT=<cockroachdb_port>",
                "-e", "CRDB_DATABASE=<cockroachdb_database>",
                "-e", "CRDB_USERNAME=<cockroachdb_user>",
                "mcp-cockroachdb"]
    }
  }
}

To use the CockroachDB MCP Docker image, just replace your image name (mcp-cockroachdb in the example above) with mcp/cockroachdb.

Configuration

The CockroachDB MCP Server can be configured in two ways: either via command-line arguments or via environment variables. The precedence is: CLI arguments > environment variables > default values.

Configuration via c

---