CockroachDB MCP Server [POC]

A Model Context Protocol (MCP) server that provides tools for interacting with CockroachDB. This server enables AI assistants to perform database operations, query data, manage schemas, and monitor cluster health through a standardized interface.

Note: This MCP Server is a proof-of-concept implementation and is not intended for production use.

Architecture

sequenceDiagram
    participant User as User
    participant Client as Claude Desktop/<br/>Cline/MCP Inspector
    participant Server as MCP Server
    participant Registry as Tool Registry
    participant DBMgr as Database Manager
    participant DB as CockroachDB

    Note over Client,DB: Initialization Phase
    Client->>Server: Connect via STDIO
    Server->>Registry: Register Tools
    Server->>DBMgr: Initialize with connection string
    DBMgr->>DB: Connect to database

    Note over User,DB: Request/Response Flow
    User->>Client: Natural language query<br/>("Show me all tables")
    Client->>Server: JSON-RPC request: tools/call<br/>(e.g., list_tables)
    Server->>Registry: Lookup tool handler
    Registry->>DBMgr: Invoke database operation
    DBMgr->>DB: Execute SQL command
    DB-->>DBMgr: Return results
    DBMgr-->>Server: Format response
    Server-->>Client: JSON-RPC response<br/>with tool results
    Client-->>User: Natural language response<br/>("Here are your tables: ...")

How It Works

1. Client Connection: AI clients (like Claude Desktop) or testing tools (like MCP Inspector) connect to the MCP server using stdio transport with JSON-RPC protocol
2. Tool Registration: The server registers database operation tools on startup
3. Connection Setup: The server connects to CockroachDB with provided connection string
4. Request Flow: Client invokes tools → MCP server processes requests → Database Manager executes SQL operations → CockroachDB returns results
5. Response: Results are formatted and returned to the client through the MCP protocol

Features

• Connection Management: Connect to CockroachDB instances and check connection status
• Database Operations: List, create, and switch between databases
• Schema Management: List tables, create tables, describe table structures, view columns and indexes
• Query Execution: Execute SQL queries, explain query plans, and view query history
• Cluster Monitoring: View cluster status and running queries

Prerequisites

• Go 1.24.3 or higher
• CockroachDB instance (local or remote)
• Access credentials for your CockroachDB cluster

Installation

1. Clone the repository:

git clone https://github.com/rahulcrl/cockroachdb-mcp-server.git
cd cockroachdb-mcp-server

2. Install dependencies:

go mod download

3. Build the server:

go build -o cockroachdb-mcp-server

Running the Server

Using Connection String

# Via command-line flag
./cockroachdb-mcp-server -connection-string "postgresql://root:password@localhost:26257/defaultdb?sslmode=disable"

# Via environment variable
export COCKROACHDB_CONNECTION_STRING="postgresql://root:password@localhost:26257/defaultdb?sslmode=disable"
./cockroachdb-mcp-server

Running with MCP Client (Claude Desktop)

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cockroachdb": {
      "command": "/path/to/cockroachdb-mcp-server",
      "args": [
        "-connection-string",
        "postgresql://root:password@localhost:26257/defaultdb?sslmode=disable"
      ]
    }
  }
}

Note: You can also start the MCP server without connection parameters and use the connect_to_cockroachdb tool to connect dynamically:

{
  "mcpServers": {
    "cockroachdb": {
      "command": "/path/to/cockroachdb-mcp-server"
    }
  }
}

Then use the `connect_to_cockroachdb

... View full README on GitHub