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: ...")

Loading

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 tool with your connection string through the MCP client interface.

Testing with MCP Inspector

The MCP Inspector is a developer tool for testing and debugging MCP servers. To use it with this server:

1. Install the MCP Inspector:

npx @modelcontextprotocol/inspector

2. Run the inspector with your server:

npx @modelcontextprotocol/inspector /path/to/cockroachdb-mcp-server -connection-string "postgresql://root:password@localhost:26257/defaultdb?sslmode=disable"

Or without connection parameters:

npx @modelcontextprotocol/inspector /path/to/cockroachdb-mcp-server

3. The inspector will open in your browser, allowing you to:

   • View all available tools
   • Test tool calls with custom parameters
   • Inspect request/response messages
   • Debug connection and query issues

4. Use the connect_to_cockroachdb tool in the inspector to establish a database connection if you started without connection parameters.

Available Tools

The MCP server provides the following tools for interacting with CockroachDB:

Category	Tool	Description	Parameters
Connection & Monitoring	connect_to_cockroachdb	Connect to a CockroachDB instance using a connection string	connection_string (required): PostgreSQL connection string
	get_connection_status	Get the current database connection status and information	None
	get_cluster_status	Get detailed status information for all nodes in the cluster	None
	show_running_queries	Show currently running queries in the cluster	None
Database Management (DDL)	list_databases	List all databases in the CockroachDB cluster	None
	create_database	Create a new database	database_name (required): Name of the database to create
	switch_database	Switch to a different database	database_name (required): Name of the database to switch to
	list_tables	List all tables in the current database	schema (optional): Schema name (defaults to 'public')
	create_table	Create a new table with specified columns	table_name (required): Name of the table to create columns (required): Column definitions
	describe_table	Get detailed information about a table including columns, types, and constraints	table_name (required): Name of the table to describe
	list_columns	List all columns for a specific table	table_name (required): Name of the table
	list_indexes	List all indexes for a specific table	table_name (required): Name of the table
Query Execution (DML/DQL)	execute_query	Execute a SQL query and return the results	query (required): SQL query to execute limit (optional): Maximum number of rows to return
	explain_query	Get the execution plan for a SQL query	query (required): SQL query to explain
	get_query_history	Retrieve recent query execution history	limit (optional): Number of recent queries to return (default: 10)

Development

Project Structure

.
├── main.go      # Server initialization and configuration
├── db.go        # Database connection management and operations
├── tools.go     # MCP tool definitions and handlers
├── go.mod       # Go module dependencies
└── README.md    # This file

Key Dependencies

• github.com/mark3labs/mcp-go - MCP server implementation
• github.com/lib/pq - PostgreSQL/CockroachDB driver

Building from Source

# Build for current platform
go build -o cockroachdb-mcp-server

# Build for specific platform
GOOS=linux GOARCH=amd64 go build -o cockroachdb-mcp-server-linux
GOOS=darwin GOARCH=arm64 go build -o cockroachdb-mcp-server-darwin-arm64
GOOS=windows GOARCH=amd64 go build -o cockroachdb-mcp-server.exe

Security Considerations

• Always use SSL/TLS in production (sslmode=require or higher)
• Store connection strings in environment variables or secure configuration management
• Use least-privilege database users for the MCP server
• Regularly rotate database credentials
• Monitor query history for unusual activity

Troubleshooting

Connection Issues

Problem: Failed to connect to database

• Verify CockroachDB is running: cockroach node status
• Check connection string format
• Verify network connectivity and firewall rules
• Ensure SSL mode matches your cluster configuration

Problem: Authentication failed

• Verify username and password
• Check user permissions in CockroachDB
• For CockroachDB Cloud, ensure you're using the correct certificate

Query Issues

Problem: Permission denied

• Verify database user has necessary privileges
• Check schema and table ownership