schemabrain

<!-- mcp-name: io.github.Arun-kc/schemabrain --> <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme-hero-dark.svg"> <img src="docs/assets/readme-hero-light.svg" alt="SchemaBrain — the trust and intelligence layer between AI agents and your database" width="100%"> </picture> </p> <h1 align="center"> <strong>Stop giving AI agents raw database connection strings.</strong> </h1> <h2 align="center"> Give them SchemaBrain instead — a read-only trust and intelligence layer where the agent never writes SQL, PII is refused before the query runs, and every call lands in a tamper-evident audit log. </h2> <p align="center"> <a href="https://github.com/Arun-kc/schemabrain/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Arun-kc/schemabrain/ci.yml?style=flat-square&label=CI&labelColor=0A0A0A&color=3ECF8E" alt="CI"></a> <a href="https://pypi.org/project/schemabrain/"><img src="https://img.shields.io/pypi/v/schemabrain?style=flat-square&label=pypi&labelColor=0A0A0A&color=3ECF8E" alt="PyPI version"></a> <a href="https://pypi.org/project/schemabrain/"><img src="https://img.shields.io/pypi/dm/schemabrain?style=flat-square&label=downloads&labelColor=0A0A0A&color=3ECF8E" alt="PyPI downloads"></a> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11%20%7C%203.12-0A0A0A?style=flat-square&labelColor=0A0A0A" alt="Python 3.11 | 3.12"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-0A0A0A?style=flat-square&labelColor=0A0A0A" alt="License: Apache 2.0"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-3ECF8E?style=flat-square&labelColor=0A0A0A" alt="MCP compatible"></a> </p> <p align="center"> <em>Works with Claude Desktop · Claude Code · Cursor · Windsurf · any MCP host</em> </p>

SchemaBrain compiles every query from definitions you control — no path from a prompt to raw SQL at your database.

Three guarantees that close the trust gap between AI agents and your database:

• Read-only by architecture — twelve MCP tools, none of which can write. No execute() tool, no query() tool, no path from agent prompt to a write at your database.
• PII-aware refusal at retrieval — PII tags propagate from the physical schema through joins and metrics. If a query touches a blocked category, SchemaBrain refuses before the database is queried.
• Cryptographic audit chain — every call, refusal, and recovery is recorded in a SHA256-hashed append-only log (best-effort: a disk-full or no-writer configuration logs a warning and continues rather than failing the query). audit verify exits non-zero if any past row was rewritten.

See it in action — ask for something the schema can't answer, and it refuses instead of fabricating a join:

You: compute usage volume by plan tier

SchemaBrain → agent: { "kind": "unreachable_entity", "recovery": { "suggested_tool": "resolve_join" } } — there's no plan_id on usage events, so it won't invent one.

Claude: I can't fake that join — here's contracted revenue by plan tier instead, which actually resolves. ✓

→ Full session, with the SQL and results

Watch it run — a live Postgres schema becomes a governed knowledge graph, the firewall computes the safe metric and refuses the leaks, and every call lands in a tamper-evident audit log. No agent, no API key:

<p align="center"> <img src="docs/assets/demo-cli-curated.gif" alt="SchemaBrain command-line walkthrough: indexing a live Postgres schema, applying the curated semantic layer of entities, joins, and metrics, then the firewall computing a safe revenue metric, refusing PII and credential leaks, recovering an unreachable join, and the operator inspecting definitions and verifying a tamper-evident audit log." width="100%"> </p>

---

uvx schemabrain init
# then: Cmd+Q Claude Desktop, relaunch, and ask: "list the entities SchemaBrain knows about"
# prefer a persistent install? pipx install schemabrain (or) pip install schemabrain

Cost: $0 to run the bundled demo (pre-curated pack, no API key) · ~$0.03 to LLM-index a fresh 84-column schema · $0 to re-index unchanged schemas. Detail in Sample session.

Status: 0.6.0 (beta). Postgres supported today (the local store itself is SQLite). SQLite / Snowflake / BigQuery / MySQL source connectors on the roadmap.

---

Contents

Read next based on what you need:

| Goal | Where to go | |---|---| | Try it on the bundled fixture | Quickstart | | Understand the safety guarantees | Safety guarantees | | Wire up your MCP client | Claude Desktop · Claude Code · Cursor · Windsurf · Cline · ChatGPT (roadmap) | | Plug into your own agent loop | docs/setup/manual.md | | Build a semantic layer | docs/semantic-layer.md | | Run in production (audit, drift, Docker) | docs/operations.md | | Observe the agent (tail, audit log, OTel) | docs/observability.md | | Compare with Querybear / Anthropic reference Postgres MCP | vs Querybear · vs Anthropic reference | | Compare with Vanna / Atlan / dbt-mcp / WrenAI | docs/landscape.md |

---

Quickstart

Just want to see what it does? uvx schemabrain demo — one command, zero prompts. Builds the sample SaaS layer, then lets you open the dashboard or run a terminal firewall showcase. No API key, and no Docker for the dashboard / showcase paths. The steps below are for wiring SchemaBrain into your own agent against your own database.

Three steps from uvx schemabrain init to a working Claude Desktop integration. If you paste your own Postgres URL — no Docker needed, ~30s. Press Enter for the bundled demo and init invokes Docker + downloads a ~67 MB embedding model first time; ~45s once cached.

1. Install

uvx schemabrain init        # zero-install: runs the wizard in one shot
# or install persistently first:
pipx install schemabrain    # (or) pip install schemabrain
schemabrain --version

Source install (git clone + uv sync --extra dev) is documented in docs/setup.md.

2. Run the activation wizard

schemabrain init

init is a seven-stage wizard that takes you from "I have a Postgres database" to "Claude Desktop can answer questions about it" in one command. On first run it prompts for what it needs:

• A Postgres URL — paste your own connection string, or press Enter to spin up a local demo Postgres container with the bundled SaaS fixture (Docker is invoked automatically; idempotent on re-runs).
• An ANTHROPIC_API_KEY — optional. Skip and the wizard still wires Claude Desktop. On the demo path, entities + metrics + joins are pre-curated from a bundled YAML pack — the semantic layer works zero-config. On your own database, entity curation can run later via schemabrain entities suggest --apply once you have a key.

SchemaBrain init — activation wizard

  [1/7] Source check       ✓ source reachable + read-only
  [2/7] Index schema       ✓ 12 tables, 84 columns indexed
  [3/7] Curate entities    ✓ 12 entities applied (bundled demo pack)
  [4/7] Curate metrics     ✓ 5 metrics applied (bundled demo pack)
  [5/7] Curate joins       ✓ 11 canonical joins applied (bundled demo pack)
  [6/7] Wire host          ✓ wrote schemabrain entry to claude_desktop_config.json
                           (default; switch with --host claude-code|cursor|windsurf|manual)
  [7/7] Next               ✓ restart your MCP host, then ask: "list the entities SchemaBrain knows about"

Full wizard reference (stages explained, flags, dbt auto-detection, --print-only for non-Claude-Desktop hosts, --no-entities / --no-metrics / --no-joins opt-outs, cost-cap pauses): docs/setup.md.

3. Restart Claude Desktop and ask

1. Quit Claude Desktop fully — Cmd+Q, not just close the window. The MCP config is only read on cold start.

2. Relaunch.

3. New conversation:

   list the entities SchemaBrain knows about

If Claude calls list_entities and reports user, order, etc., you're done. If not, see Troubleshooting.

After the wizard, schemabrain inspect shows what the agent has and schemabrain tail streams every tool call live — see docs/operations.md.

Your project files

init writes just ./schemabrain.db (the local store — gitignore it) plus your host config. To tune the PII policy and semantic layer as editable YAML, re-run with --emit-yaml-dir:

schemabrain init --url-env DATABASE_URL --emit-yaml-dir ./schemabrain
# → ./schemabrain/pii_policy.yaml + entities/ + metrics/ + joins/

Edit a file, schemabrain apply ./schemabrain, schemabrain check to validate, restart serve. There is no schemabrain.yaml — config is CLI flags + SCHEMABRAIN_* env vars (auto-loaded from .env) + that YAML tree. Full map: Your project.

---

Safety guarantees

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme-architecture-compact-dark.svg"> <img src="docs/assets/readme-architecture-compact-light.svg" alt="SchemaBrain architecture: agent talks to SchemaBrain over MCP stdio (12 read-only tools); SchemaBrain emits parameterized SQL to Postgres; the SchemaBrain boundary is the trust boundary; audit log is tamper-evident." width="100%"> </picture> </p>

Six properties SchemaBrain enforces at the SQL boundary today:

1. Read-only by architecture, not configuration

The MCP surface exposes twelve tools — none of which can write. No execute(), no query(), no path from agent prompt to a write at your database, regardless of session state — the guarantee is structural, not a flag the agent can flip. schemabrain serve also pins default_transaction_read_only=on as belt-and-suspenders. Read-only by architecture →

2. PII-aware refusal at the get_metric tool boundary

Any get_metric touching a blocked PII category returns a refused envelope — the compiled SQL never runs and the refusal lands in mcp_audit. describe_entity enforces the same at the column level (blocked columns ship redacted=True). init blocks the catastrophic-leak set by default (credential,payment_card,government_id); --pii-block replaces the set, so widen by listing the full target. Detection is column-name pattern matching across twelve GDPR / CCPA / HIPAA / PCI categories; content-aware classification is on the roadmap. PII taxonomy & propagation →

3. Tamper-evident audit log

Every tool call writes one row to an append-only mcp_audit table — PII categories, content-addressable fingerprints, sha256 hash chain. audit verify re-walks the chain and exits non-zero if any past row was rewritten.

schemabrain audit verify   # exit 0 = chain clean

Tamper-evident audit chain →

4. Failure is a contract, not a string

Every non-success call — refused, error, or degraded — returns a structured recovery.suggested_args block, not a message to parse. PII blocks (status: "refused") ship the entity to ret