MCP Cockroachdb

🚀 CockroachDB MCP Server

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

🚀 Quick Start

The CockroachDB MCP Server supports the stdio transport. Support for the streamable-http transport will be added in a future release. You can quickly start using it with uvx as shown in the Installation section.

✨ Features

• Natural Language Queries: Allows 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: Checks and monitors the CockroachDB cluster status, including node health and replication.
• Database Operations: Performs all operations related to databases, such as creation, deletion, and configuration.
• Table Management: Handles 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.

📦 Installation

Quick Start with uvx

The easiest way to use the CockroachDB MCP Server is with uvx. You can run it directly from GitHub (from a branch or use a tagged release). It's recommended to use a tagged release as the main branch is under active development and may contain breaking changes.

uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git@0.1.0 cockroachdb-mcp-server --url postgresql://localhost:26257/defaultdb

Check the release notes for the latest version in the Releases section. Additional examples are as follows:

# 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

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

After cloning the repository, installing dependencies, and verifying that you can run the server, you can configure Claude Desktop or any other MCP Client to use this MCP Server by running the main file directly.

{
    "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

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

Build the image:

docker build -t mcp-cockroachdb .

Configure the client (e.g., for Claude Desktop):

{
  "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 official image, replace mcp-cockroachdb with mcp/cockroachdb.

📚 Documentation

Configuration

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

Configuration via command line arguments

# Basic CockroachDB connection
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
  --host localhost \
  --port 26257 \
  --db defaultdb \
  --user root \
  --password mypassword

# Using CockroachDB URI (simpler)
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
  --url postgresql://root@localhost:26257/defaultdb

# SSL connection
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
  --url postgresql://user:pass@cockroach.example.com:26257/defaultdb?sslmode=verify-full&sslrootcert=path/to/ca.crt&sslcert=path/to/client.username.crt&sslkey=path/to/client.username.key

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

Available CLI Options:

Configuration via Environment Variables

You can set environment variables in two ways:

1. Using a .env File: Place a .env file in your project directory with key - value pairs for each environment variable. Tools like python-dotenv, pipenv, and uv can automatically load these variables when running your application.

cp .env.example .env

2. Setting Variables in the Shell:

export CRDB_URL= postgresql://root@127.0.0.1:26257/defaultdb

Integrations

OpenAI Agents SDK

Integrate this MCP Server with the OpenAI Agents SDK.

pip install openai-agents

Configure the OpenAI token:

export OPENAI_API_KEY="<openai_token>"

Run the application:

python3 examples/cockroachdb_assistant.py

You can troubleshoot using the OpenAI dashboard.

Augment

Configure the CockroachDB MCP Server in Augment by importing the server via JSON:

{
  "mcpServers": {
    "CockroachDB MCP Server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/cockroachdb/mcp-cockroachdb.git",
        "cockroachdb-mcp-server",
        "--url",
        "postgresql://root@localhost:26257/defaultdb"
      ]
    }
  }
}

Claude Desktop

Add the following JSON to your claude_desktop_config.json:

{
    "mcpServers": {
        "cockroach-mcp-server": {
            "type": "stdio",
            "command": "/opt/homebrew/bin/uvx",
            "args": [
                "--from", "git+https://github.com/amineelkouhen/mcp-cockroachdb.git",
                "cockroachdb-mcp-server",
                "--url", "postgresql://localhost:26257/defaultdb"
            ]
        }
    }
}

To test via Smithery:

npx -y @smithery/cli install @amineelkouhen/mcp-cockroachdb --client claude

VS Code with GitHub Copilot

Enable the agent mode tools. Add the following to your settings.json:

{
  "chat.agent.enabled": true
}

Start the server using uvx:

"mcp": {
    "servers": {
        "CockroachDB MCP Server": {
        "type": "stdio",
        "command": "uvx", 
        "args": [
            "--from", "git+https://github.com/amineelkouhen/mcp-cockroachdb.git",
            "cockroachdb-mcp-server",
            "--url", "postgresql://root@localhost:26257/defaultdb"
        ]
        }
    }
}

Or start the server using uv and configure mcp.json or settings.json:

{
  "servers": {
    "cockroach": {
      "type": "stdio",
      "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>"
      }
    }
  }
}

Cursor

Read the configuration options here and input your selections with this link:

🔧 Technical Details

Tools

The CockroachDB MCP 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.

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.

💻 Testing

You can use the MCP Inspector for visual debugging of this MCP Server.

npx @modelcontextprotocol/inspector uv run src/main.py

🤝 Contributing

1. Fork the repository
2. Create a new branch (feature - branch)
3. Commit your changes
4. Push to your branch and submit a pull request.

📄 License

This project is licensed under the MIT License.

🌟 Quality Badge

📞 Contact

If you have any questions or need support, please feel free to contact us through GitHub Issues.