erdlens

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.

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

Related MCP server: AI Diagram Maker MCP Server

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

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