# SchemaBrain

SchemaBrain gives AI agents controlled, read-only access to a Postgres schema with PII checks and an audit trail. Use it for governed data queries.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 12
- Author: Arun-kc
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Arun-kc/schemabrain
- Updated: 2026-08-24
- HTML: https://affpapa.org/en/nevibecode/mcp/schemabrain

## What it does

SchemaBrain places a controlled layer between an AI agent and a Postgres database. It exposes twelve MCP tools built around defined entities, joins, and metrics. None of them writes to the database or offers arbitrary SQL execution, so a prompt cannot directly turn into a database write.

PII labels flow from the physical schema through joins and metrics. When a request reaches a blocked category, the server refuses it before querying the database. Calls, refusals, and recovery events go into an append-only SHA256-hashed audit log; `audit verify` reports rewritten rows. Postgres is supported, while the local store uses SQLite. Set `DATABASE_URL` before connecting, or the server will not start.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `DATABASE_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add schemabrain -e DATABASE_URL=<DATABASE_URL> -- uvx schemabrain
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from schemabrain <command>

### Codex

**Platform CLI**
```bash
codex mcp add schemabrain --env DATABASE_URL=<DATABASE_URL> -- uvx schemabrain
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from schemabrain <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "schemabrain": {
            "command": "uvx",
            "args": [
                "schemabrain"
            ],
            "env": {
                "DATABASE_URL": "<DATABASE_URL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from schemabrain <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "schemabrain": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "schemabrain"
            ],
            "env": {
                "DATABASE_URL": "<DATABASE_URL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from schemabrain <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e DATABASE_URL=<DATABASE_URL> schemabrain uvx schemabrain
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from schemabrain <command>

## When to use it
- inspect the entities available to an agent
- calculate metrics through approved joins
- block PII access before a query runs
- record calls and refusals in an audit log
- detect rewritten audit records

## Example prompts
- List the entities SchemaBrain knows about in the connected database.
- Calculate revenue by plan tier using only approved joins.
- Check this customer-data request and refuse it if it touches PII.

## Similar
- [januscope](https://affpapa.org/en/nevibecode/mcp/januscope.md) — MCP server · ★ 32
- [MCP Gateway](https://affpapa.org/en/nevibecode/mcp/panossalt-mcp-gateway.md) — MCP server · ★ 6
- [platform-datamask-run](https://affpapa.org/en/nevibecode/skills/platform-datamask-run.md) — skill · 1400 installs
- [gemini-history-analyzer](https://affpapa.org/en/nevibecode/skills/gemini-history-analyzer.md) — skill · 321 installs
- [Covenant Guard](https://affpapa.org/en/nevibecode/mcp/covenant-guard.md) — MCP server · ★ 8
- [Arcaeon](https://affpapa.org/en/nevibecode/mcp/arcaeon.md) — MCP server · ★ 1

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md