Django ORM Lens

See your entire Django schema — in your editor, in your terminal, and from your AI agent.

Every app. Every model. Every field. Every relationship. Grouped, navigable, and one keystroke away from a live ER diagram.

🎯 Pick your path

Django ORM Lens ships as three distributions on one core — pick the one that matches your workflow. Each takes under 60 seconds.

Editor user (VS Code / Cursor / Windsurf): install the extension → open any Django project → sidebar tree + ER diagram appear.

code --install-extension frowningdev.django-orm-lens

Terminal / CI user: install from PyPI → run django-orm-lens in any directory that contains Django apps.

pip install django-orm-lens
django-orm-lens               # welcome + commands
django-orm-lens scan          # scan cwd for apps and models

AI coding agent user (Cursor / Aider / Continue / Zed): install with MCP extras → add one JSON block to your client config.

pip install "django-orm-lens[mcp]"

Then the MCP config snippet in the Integrations section below. Point DJANGO_ORM_LENS_ROOT at your Django project's absolute path.

Related MCP server: django-mcp-inspector

📊 Traction

Updated 2026-07-15. PyPI weekly / monthly, GitHub stars / forks, and PyPI / VS Code version badges auto-refresh live.

If the tool saves you a grep next time you touch a strange Django project — star helps others find it.

⚡ Install

VS Code / Cursor / Windsurf / any Code fork:

code --install-extension frowningdev.django-orm-lens

Or search Django ORM Lens in the Extensions view.

Terminal & AI coding agents:

pip install django-orm-lens              # CLI only
pip install "django-orm-lens[mcp]"       # + MCP server for AI agents

Requires Python 3.9+. Zero runtime dependencies for the CLI.

🎯 The problem

Works offline. Works on a broken venv. Works on someone else's laptop. Works in CI.

You open a Django project. It has 20 apps. You need to answer a simple question:

"Which app owns the Order model, and how is it connected to User?"

Today, that means: Ctrl+P, "models", scroll through 30 hits, open five files, Ctrl+F for class Order, read through 400 lines of ForeignKey('otherapp.Something') strings, try to remember what you learned two files ago.

Half a day gone. Every time. On every project.

✨ With Django ORM Lens

📚 A tree of everything

Every app → every model → every field → every Meta option. Grouped by application, sorted alphabetically, expandable.

Icons distinguish CharField from ForeignKey from ManyToManyField at a glance.

🕸️ A live ER diagram

One command opens a Mermaid entity-relationship diagram of your entire schema. Watch it redraw as you edit. Export to SVG.

ForeignKey, OneToOneField, and ManyToManyField become proper cardinality arrows.

🔎 Hover for relations

Hover over ForeignKey('app.Model') in any Python file → a card pops up with the target model's fields, relations, and a "Jump to" link. No Ctrl+F, no file dialog.

🧭 Jump-to-definition

Click any field in the tree → cursor lands on the exact line. Filter the tree by app or model name. Split models/ packages are fully supported.

⚡ Zero configuration

No DJANGO_SETTINGS_MODULE. No runserver. Parses models.py statically. Works with a broken venv, a missing dependency, or on someone else's laptop.

🎨 Native VS Code UI

Dark theme. Light theme. Your theme. Follows your icon theme, your font, your key bindings. Nothing garish, nothing branded.

📸 What it looks like

Also included in the extension:

• 🕸️ Live ER diagram — Mermaid cardinality arrows, edge labels (CASCADE, through Model, as related_name), theme-aware, one-click SVG export

• 🔎 Hover cards — over any ForeignKey('app.Model') or ManyToManyField(...), with a one-click jump link

• 🧭 CodeLens — above every class Model line: field count, relation count, and an Open ER diagram action

• 🎨 Named themes — auto / default / dark / forest / neutral for the diagram webview

🤖 For terminals and AI coding agents

The same parser that powers the VS Code extension ships as a standalone Python package — with an optional MCP (Model Context Protocol) server so any MCP-compatible AI agent can navigate your Django schema without importing Django or booting your app.

CLI

django-orm-lens scan -f json          # every app, every model, every field
django-orm-lens describe blog.Post    # one model in Markdown
django-orm-lens hover blog.Post       # compact hover card
django-orm-lens list | fzf            # flat app.Model — pipes anywhere
django-orm-lens er > schema.mmd       # Mermaid ER diagram

Every command accepts --path <dir> and --exclude <glob>.

MCP server

Register it once with your agent and it exposes five read-only tools:

# Start it directly
django-orm-lens-mcp

# Or via the CLI subcommand
django-orm-lens mcp

Set DJANGO_ORM_LENS_ROOT=/abs/path/to/project to point it anywhere.

🔌 Integrations

Example: Cursor / any MCP client

{
  "mcpServers": {
    "django-orm-lens": {
      "command": "django-orm-lens-mcp",
      "env": { "DJANGO_ORM_LENS_ROOT": "/abs/path/to/your/project" }
    }
  }
}

🚀 Get started (30 seconds)

In VS Code:

1. code --install-extension frowningdev.django-orm-lens

2. Open a folder with a manage.py or models.py

3. Click the Django ORM Lens icon in the activity bar

4. Expand apps → models → fields

5. Click the type-hierarchy icon at the top of the panel → ER diagram opens beside your code

In a terminal:

pip install django-orm-lens
cd my-django-project
django-orm-lens scan -f table

As an AI agent tool:

pip install "django-orm-lens[mcp]"

…then register django-orm-lens-mcp in your agent's MCP config (see the Integrations table above).

No settings screen. No sign-in. No telemetry.

🎯 Who this is for

• Django developers joining a codebase with 10+ apps and getting lost in models.py sprawl.

• Contract / freelance engineers who need to grasp an unfamiliar Django project in the first hour, not the first week.

• Teams onboarding new hires who want a one-glance schema view without spinning up documentation infrastructure.

• AI-agent power users (Cursor / Aider / Zed / Continue / any MCP-compatible client) who need the agent to answer schema questions accurately — without giving it database credentials or booting Django.

• CI pipelines that verify schema shape (e.g. "did we accidentally break a related_name?") without importing the project.

• Solo indie devs on a broken venv or someone else's laptop — no runserver, no manage.py migrate, still works.

🗺️ Market position

Django ORM Lens sits at the intersection of editor tooling and AI-agent tooling — a slot no existing package covers:

Django ORM Lens is the only tool that ships three surfaces from one parser: a VS Code extension (any Code fork), a zero-dep CLI (terminals + CI), and an MCP server (AI agents). All static. All free. All MIT.

🤔 How is this different?

django-schema-graph has not been updated since 2023-05 and does not test Django 5.x.

⚙️ Configuration

The defaults are opinionated and sensible. If you need to tweak:

// .vscode/settings.json
{
  "djangoOrmLens.excludeGlobs": [
    "**/migrations/**",
    "**/node_modules/**",
    "**/venv/**",
    "**/.venv/**",
    "**/env/**"
  ],
  "djangoOrmLens.autoRefresh": true
}

🧭 Commands

Open the command palette (Ctrl+Shift+P / Cmd+Shift+P) and type "Django ORM Lens":

🗺️ Roadmap

Shipped

• Sidebar tree grouped by app

• Live Mermaid ER diagram

• Hover cards over ForeignKey('app.Model')

• Filter tree by name

• Split models/ package support

• Export ER diagram as SVG

• Python CLI + MCP server for terminals and AI agents

• Welcome view for empty workspaces

• Path-safe jump-to-definition and sanitized hover markdown

• v0.3.0 — CodeLens above each model class (N fields · N relations · Open ER diagram)

• v0.3.0 — Edge labels on the diagram (CASCADE, SET_NULL, PROTECT, related_name)

• v0.3.0 — Named color themes (auto / default / dark / forest / neutral)

• v0.3.1 — through_model on M2M edges (contributed by @kingrubic)

• v0.3.1 — Listed in the official MCP Registry + Glama.ai

Next

• Zoom + minimap + auto-layout inside the webview (#4)

• ORM query autocomplete inside .filter() / .exclude() / .annotate() (#3)

• App / model toggle checkboxes to declutter huge schemas

Later

• Migration dependency graph

• Third-party field support (django-mptt, django-taggit, django-model-utils)

• JetBrains / PyCharm plugin (if there is demand)

Vote by 👍-ing the corresponding issue.

❓ FAQ

🆘 Support

• 🐛 Bug reports — GitHub Issues (please include a minimal models.py snippet)

• 💡 Feature requests / ideas — GitHub Discussions

• 📝 Marketplace reviews — rate the extension (the fastest signal that keeps this project moving)

• 🐍 PyPI page — pypi.org/project/django-orm-lens

• 💚 Sponsor — github.com/sponsors/FROWNINGdev

📜 License

MIT © FROWNINGdev

Made for developers who care about their codebase.

Marketplace · PyPI · GitHub · Issues · Discussions · Sponsor