Skip to main content
Glama
christianhoustonfloyd

schema-viz

by christianhoustonfloyd
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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.

Related MCP server: erdlens

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.

Available Tools

2 tools
display_schemaA

Render a database schema as an interactive, dbdiagram.io-style ER diagram (draggable table cards, relationship lines, pan/zoom) in the local browser. Accepts DBML text via dbml, or a path to a .dbml file via filePath. With neither, it shows the bundled project schema. The browser view live-reloads when you call this again with an updated schema.

ParametersJSON Schema
NameRequiredDescriptionDefault
dbmlNoRaw DBML source (dbdiagram.io syntax). Takes precedence over filePath.
openNoOpen the browser automatically on first render (default true).
titleNoTitle shown in the diagram toolbar.
contextNoOptional extra panels beyond the schema diagram. When provided, an 'Infrastructure' and/or 'How it was built' tab appear. Shape: { infrastructure: [{ title, rows: [[label, value], ...] }], buildSteps: [{ phase, items: [{ what, why }] }] }. Use for live wiring (database, auth/OAuth, env var NAMES only — never secret values, repo, MCP) and the build narrative.
filePathNoPath to a .dbml file (absolute, or relative to the server's cwd).

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the behavioral burden. It discloses the local-browser rendering, live-reload behavior, input precedence, and fallback to the bundled schema. It does not mention non-destructiveness or return behavior explicitly, but for a rendering tool the disclosed behavior is reasonably transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three focused sentences with the core purpose front-loaded. It avoids restating parameter descriptions and every sentence adds useful information: what it renders, how inputs are selected, and how the browser view updates.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a viewer tool with five parameters and a nested `context` object, the description plus rich schema descriptions cover input modes, fallback behavior, and live reload. No output schema exists, but the tool's visible output is the browser diagram, so return-value details are not critical here. Minor gaps like persistence or close behavior do not materially hurt usability.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter meaning beyond the schema by stating that `dbml` takes precedence over `filePath` and that supplying neither falls back to the bundled project schema. This clarifies relationships the individual parameter descriptions do not fully convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Render'), resource ('database schema'), and output form ('interactive, dbdiagram.io-style ER diagram'), which is clearly distinct from the sibling get_schema_viewer_status. The added details about draggable cards, relationship lines, and pan/zoom make the tool's function unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit input-selection guidance: use `dbml` for raw DBML, `filePath` for a .dbml file, and neither for the bundled schema. However, it does not position this tool against get_schema_viewer_status or state any when-not-to-use conditions, so the guidance stops short of full alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_schema_viewer_statusA

Return whether the schema viewer server is running and its URL.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the core behavior (returns running status and URL) but does not disclose edge-case behavior such as what is returned when the server is not running (null URL, error, or false flag). The 'running' semantics are also undefined.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single 13-word sentence with zero waste. The key verb and resource are front-loaded, and everything stated earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema status check, the description covers the essential contract: what is returned. It could optionally describe the return shape (e.g., boolean + URL field) or suggest using it before display_schema, but nothing critical is missing for such a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so per the rubric the baseline is 4. With an empty schema, there is nothing for the description to explain about arguments, making this dimension inherently satisfied.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Return') with a clear resource (schema viewer server status) and names the output (running state + URL). It is unambiguous about what the tool does, though it does not explicitly differentiate from its sibling 'display_schema' — the distinction is implied by subject matter rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to call this tool versus 'display_schema' or any other alternative. An agent must infer that a status check likely precedes schema display. There are no explicit conditions, exclusions, or workflow hints.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observeddisplay_schema
    • First observedget_schema_viewer_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely separate concerns: one checks server status, the other renders a schema. There is no overlap or ambiguity in their purposes.

Naming Consistency5/5

Both tool names follow a clear verb_noun snake_case pattern: get_schema_viewer_status and display_schema. The naming is consistent and predictable.

Tool Count3/5

Two tools is borderline thin for a server, though each serves a clear purpose. The scope is narrow, but a stop-viewer or close-browser tool would make the set feel more complete.

Completeness4/5

The core workflow of rendering a schema and checking viewer status is covered. The lack of a way to close or stop the viewer is a minor gap that agents can work around by simply refreshing or leaving the browser tab.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mermaid-live-mcp

    iishyfishyy
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server that generates Mermaid diagrams with live browser preview, supports real-time rendering and SVG/PNG export.
    12
    -

  • erdlens

    ryanda9910
    A
    license
    A
    quality
    A
    maintenance
    MCP server that reads your database schema from SQL DDL, Prisma, Drizzle, TypeORM, or SQLAlchemy, generates a Mermaid ER diagram, and writes it into your documentation, with drift detection to keep diagrams up-to-date.
    5
    1
    MIT

  • sqemo-mcp

    sqemo
    A
    license
    B
    quality
    B
    maintenance
    MCP server for Sqemo, a web-based ERD tool with team naming standards. 34 tools: read/edit entities, attributes, and relationships; generate physical names from a shared glossary and naming rules; SQL (7 dialects) and DBML import/export; ERD lint, diff, and ALTER generation.
    36
    MIT