erdlens

<p align="center"> <img src="assets/logo.svg" alt="erdlens" width="96" height="96" /> </p>

<h1 align="center">erdlens</h1>

<p align="center"><b>Your schema becomes an ER diagram, straight into your docs. And it tells you when the diagram goes stale.</b></p>

<p align="center"> 🇺🇸 English · <a href="README.id.md">🇮🇩 Bahasa Indonesia</a> · <a href="README.zh-CN.md">🇨🇳 简体中文</a> </p>

<p align="center"> <img alt="license" src="https://img.shields.io/badge/license-MIT-6C8EEF" /> <img alt="runtime deps" src="https://img.shields.io/badge/runtime%20deps-0-6C8EEF" /> <img alt="tests" src="https://img.shields.io/badge/tests-57%20passing-6C8EEF" /> <img alt="mcp" src="https://img.shields.io/badge/MCP-server-6C8EEF" /> <img alt="typescript" src="https://img.shields.io/badge/TypeScript-MVVM-6C8EEF" /> </p>

<p align="center"> <img src="assets/showcase.gif" alt="erdlens turning a schema into an ER diagram, a workflow into a flowchart, and catching drift after a migration" width="720" /> </p>

---

You ask Claude Code to document your database. It writes the doc, you generate an ER diagram in some other tool, then you copy-paste the diagram back in. Two tools, double work, and the moment someone runs a migration the diagram in the doc is quietly wrong.

erdlens is an MCP server that closes that loop. Claude Code reads your schema, turns it into a Mermaid ER diagram, and writes it into the document in one pass. No second tool, no copy-paste. And it can check later whether that diagram still matches the schema.

Why it's different

The existing diagram MCP servers render Mermaid you already wrote. erdlens starts a step earlier: it reads the schema for you, and a step later: it watches for drift.

	render your Mermaid	read the schema	write into the doc	drift-check
mermaid-preview MCPs	✅	❌	partial	❌
mermerd (CLI, not MCP)	❌	✅ (DB only)	❌	❌
erdlens	✅	✅ (5 sources)	✅	✅

Schema sources: SQL DDL, Prisma, Drizzle, TypeORM, SQLAlchemy — file or text, auto-detected.

Install (Claude Code)

claude mcp add erdlens -- npx -y github:ryanda9910/erdlens

Or point at a local clone:

git clone https://github.com/ryanda9910/erdlens
claude mcp add erdlens -- node /abs/path/to/erdlens/bin/erdlens.js

Then just ask Claude Code: "document the database and put an ER diagram in docs/schema.md". It calls render_erd and the diagram lands in the file.

Tools

tool	what it does
schema_to_erd	schema (path or text) → Mermaid erDiagram + a ```mermaid fenced block to paste anywhere
render_erd	writes the ERD to disk: .mmd source, an embeddable .md, and a self-contained .html preview — so it goes straight into a doc, no copy-paste
drift_check	compares an ERD already in a .mmd/.md against the current schema, and reports every table, column, and relation added or removed since. Run it in CI so a stale diagram fails the build
workflow_to_diagram	a workflow spec (a tiny text DSL or JSON steps) → Mermaid flowchart + fenced block. Document a process, pipeline, or state machine next to the ERD
render_workflow	same as render_erd, for workflows — writes the flowchart to disk, embeddable

The drift check

This is the part that keeps docs honest. After a migration:

$ erdlens drift docs/schema.md db/schema.sql
Diagram is stale. It drifted from the current schema:
  + tables added since: audit_logs
  ~ posts: +published +slug
  + relations added: posts->users
Regenerate with render_erd to fix.

Exit code is non-zero when stale, so it drops into a CI step or a pre-commit hook.

Workflows too

Not just data. Give it a workflow and it draws the flowchart — same "into your docs" path.

# publish.flow
start -> draft
draft -> review
review -> publish : approved
review -> draft : changes
publish -> done

erdlens flow publish.flow

flowchart TD
  start(["start"])
  ...
  review -->|approved| publish
  review -->|changes| draft

Ask Claude Code "put the publish workflow in docs/flow.md" and it calls render_workflow.

Also a CLI

Without an MCP client:

erdlens erd db/schema.sql            # print the Mermaid ERD
erdlens erd prisma/schema.prisma     # auto-detects Prisma
erdlens flow pipeline.flow           # print a Mermaid flowchart
erdlens drift docs/erd.mmd db/schema.sql   # exit 1 if drifted
erdlens tune                         # run the self-check loop (below)

Self-improving loop

erdlens tune is a maker → checker → reflect loop: it runs every parser on a fixture plus a drift scenario (maker), an independent grader flags anything that passed before and fails now (checker), and it persists per-source pass state to ~/.erdlens/memory.json (reflect). It's how the parsers stay honest as new schema dialects get added — a regression surfaces instead of slipping through.

Tests

npm test    # builds, then 57 assertions: 24 schema engine + 14 workflow + 19 MCP stdio

There's also an end-to-end script that drives the whole thing through a real Claude Code run (bash test/e2e.sh, needs the claude CLI logged in).

How it's built

TypeScript, laid out MVVM:

• Model (src/model/) — pure logic: schema parsers, workflow parser, drift diff, types.
• ViewModel (src/viewmodel/) — orchestration: the tool operations and the self-improving loop.
• View (src/view/) — surfaces: the JSON-RPC MCP server, the CLI, and Mermaid/HTML rendering.

Zero runtime dependencies. The MCP server is a from-scratch JSON-RPC stdio implementation; the HTML preview loads Mermaid from a CDN only when you open it in a browser.

License

MIT