cockroachdb-mcp-server

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
• ✅ 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

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

🔐 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

📘 View full API reference →

📘 View hosted API Docs

🧱 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()
);

🔗 Related Projects

• cockroachdb-mcp-client: CLI tool to manage MCP contexts, simulate LLM runs, export, and batch simulate across providers.

🙌 Contributions

This project is designed for internal and community use.

PRs welcome to extend functionality (auth, deployment support, /evaluate, telemetry, etc.).