mcp-cockroachdb

This CockroachDB MCP Server provides a natural language interface that lets LLMs and agents interact with a CockroachDB cluster through the MCP (Model Content Protocol). It supports cluster monitoring, database operations, table management, and a query engine. Users can issue natural language requests such as checking node health, listing databases, creating tables, running SQL queries, and retrieving query plans. The server is designed to work with MCP clients (e.g., Claude Desktop, Cursor) and can be driven either via the uvx entry point or directly by vegetation through the main Python entry point in development setups. To start using it, run the MCP server with uvx (or your preferred transport) and connect your MCP client to the exposed endpoints, then craft prompts that map to the provided tool categories like Cluster Monitoring, Database Operations, Table Management, and Query Engine.

Prerequisites:

• Python 3.13+ (as indicated by the project)
• git
• uv (the Python environment tool used by this MCP server) or an environment compatible with uvx

Installation steps:

1. Quick start (via uvx):

   • Ensure Python is installed and accessible in your PATH.
   • Install uvx as described in the project instructions (typically via pipx or pip with uv).
   • Run the MCP server using the example command from the README: uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --url postgresql://localhost:26257/defaultdb

2. Development installation (clone and install dependencies):

   • git clone https://github.com/amineelkouhen/mcp-cockroachdb.git
   • cd mcp-cockroachdb
   • uv venv
   • source .venv/bin/activate
   • uv sync
   • uv run cockroachdb-mcp-server --help
   • Or run the main file directly (uses environment variables): uv run src/main.py

3. Configuration for clients (example provided for Claude Desktop):

   • Prepare the client config JSON (see README example) to point to the uvx command path and pass the necessary environment variables for CockroachDB credentials.

Prerequisites recap:

• Access to a CockroachDB instance (local or remote) with appropriate credentials
• A client capable of MCP (Claude Desktop, Cursor, etc.)
• Network access between the MCP server and the CockroachDB instance

Tips and common issues:

• Transport support: The server in this setup supports stdio and streamable-http transports. Choose the one that fits your MCP client.
• If you run locally for development, you may need to adapt environment variables for CRDB settings (host, port, database, user, password, TLS settings).
• When running from Git, ensure you’re using a tagged release if you want stability; the main branch may contain breaking changes.
• For Claude Desktop integration, fill in the sample claude_desktop_config.json with your uvx path and the correct main.py path, and be sure to provide your CockroachDB credentials and TLS config if required.
• If you encounter connection issues, verify that the CockroachDB URL, host, port, database, and credentials match what the server expects, and check firewall rules.
• For production usage, consider securing TLS certificates and using proper CA paths and client certificates as needed.