schema-viz MCP server

A local MCP server that renders a database schema as an interactive, dbdiagram.io-style ER diagram in your browser: draggable table cards, color-coded headers, PK/FK/unique badges, relationship lines, pan, and zoom. No internet, no account — it runs entirely on this machine.

How it works

• You give it DBML (the same syntax as dbdiagram.io) — either inline text or a path to a .dbml file. With no input it shows the bundled schema.dbml (the LLM-Tinder schema).
• It parses the DBML (small dependency-free parser in lib/parseDbml.js), renders a self-contained HTML page, serves it from a local HTTP server (http://127.0.0.1:4477), and opens your browser.
• Call it again with an updated schema and the open tab auto-reloads.

Tools

Tool	What it does
display_schema	Render & open a schema. Args: dbml (text), filePath (path to .dbml), title, open (bool).
get_schema_viewer_status	Report whether the viewer is running and its URL.

Register with Claude Code

A project-scoped .mcp.json is already created at the repo root pointing at schema-mcp/index.js. Restart Claude Code (or approve the server when prompted) and the schema-viz tools become available. Verify with /mcp.

To register it globally instead:

claude mcp add schema-viz -- node "$(pwd)/schema-mcp/index.js"

Try it without MCP

cd schema-mcp
npm install
npm run demo        # parses schema.dbml, serves it, opens the browser

Diagram controls

• Drag a table header to move it; relationship lines follow.
• Drag the background to pan; scroll to zoom (or use the toolbar + / −).
• Auto-arrange re-packs the tables; Reset restores the default view.

Config

• Port: set SCHEMA_VIZ_PORT (default 4477).

Slash commands (bonus)

commands/ holds the versioned source for the companion Claude Code slash commands:

• schema.md → /schema — render the current project's .dbml as the interactive diagram.
• xray.md → /xray — explain any project (structure, stack, backend, live runtime) and feed the visualizer's Infrastructure / How-it-was-built tabs via display_schema's context arg.

These must live in ~/.claude/commands/ to work — this folder is the backup / source of truth. Install with: cp commands/*.md ~/.claude/commands/

Tabbed dashboard (optional)

Pass a context object to display_schema to turn the diagram into a multi-tab dashboard:

• Schema — the ER diagram (always present).
• Infrastructure — cards of { title, rows: [[label, value]] }: database, auth, hosting, env var names (never values), MCPs. Reproducible from a project's files.
• How it was built — buildSteps: [{ phase, items: [{ what, why }] }], a step-by-step story.

With no context, only the Schema tab shows (backward compatible). The /xray command assembles this context automatically from the project.