Skip to content

cockroachdb-mcp-server

PyPI Python License CI

A Model Context Protocol (MCP) server implemented in Python using FastAPI and CockroachDB.

🧠 What This Is

cockroachdb-mcp-server is a production-grade, spec-aligned MCP server that:

  • Implements the Model Context Protocol
  • Uses CockroachDB as a resilient, SQL-compatible backend
  • Exposes full CRUD APIs for managing model contexts
  • Stores context definitions as JSONB, allowing arbitrary input/output schema
  • Works seamlessly with the cockroachdb-mcp-client CLI

✅ Feature Highlights

  • ✅ REST API for MCP context management (/contexts)
  • ✅ Schema bootstrapping via CLI flag or env var
  • ✅ CRDB URL auto-detection and dialect fix
  • ✅ ASCII banner and version info
  • ✅ Structured logging and configurable log level
  • ✅ Ready for /run, /deploy, /evaluate extensions

🚀 Quickstart

📦 Install from PyPI

pip install cockroachdb-mcp-server
````

### 🏃 Run with schema init

```bash
cockroachdb-mcp-server serve --init-schema --log-level INFO

Or:

export MCP_AUTO_INIT_SCHEMA=true
cockroachdb-mcp-server serve

Server runs at http://localhost:8081 by default

🔧 CLI Usage

cockroachdb-mcp-server serve --init-schema
cockroachdb-mcp-server serve --port 8081 --host 127.0.0.1 --reload
cockroachdb-mcp-server --version
cockroachdb-mcp-server --banner

🔐 Configuring the Database

✅ Set the CRDB_URL environment variable

export CRDB_URL="postgresql://root@localhost:26257/defaultdb?sslmode=disable"

Automatically rewritten to cockroachdb://... under the hood for compatibility.

Alternatively, set it directly:

export CRDB_URL="cockroachdb://root@localhost:26257/defaultdb?sslmode=disable"

✅ Both formats are supported.

🧪 API Endpoints

Method Path Description
POST /contexts Create a context
GET /contexts List all contexts
GET /contexts/{id} Get context by ID
PUT /contexts/{id} Update context
DELETE /contexts/{id} Delete context

📘 View full API reference →

🧱 Schema Auto-Bootstrap

Run this manually:

cockroachdb-mcp-server serve --init-schema

Or automatically with:

export MCP_AUTO_INIT_SCHEMA=true

The schema created is:

CREATE TABLE IF NOT EXISTS mcp_contexts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  context_name STRING NOT NULL,
  context_version STRING NOT NULL,
  body JSONB NOT NULL,
  created_at TIMESTAMP DEFAULT now()
);
  • cockroachdb-mcp-client: CLI tool to manage MCP contexts, simulate LLM runs, export, and batch simulate across providers.