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.

---

⚡ 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

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

🤖 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:

Tool	Purpose
list_apps	Every Django app in the workspace with model counts
list_models	Flat app.Model list, optional app filter
describe_model	Full field / relation / Meta detail for one model
find_relations	Inbound + outbound relations for one model
er_diagram	Mermaid erDiagram for the whole workspace

# 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

Client	How to enable	Status
VS Code	code --install-extension frowningdev.django-orm-lens	✅
Cursor	same VSIX + optional MCP entry in ~/.cursor/mcp.json	✅
Windsurf / VSCodium / any Code fork	install the VSIX from the Marketplace or GitHub Releases	✅
Aider	add django-orm-lens-mcp to your mcp.json	✅ (via MCP)
Continue.dev	register the MCP server in ~/.continue/config.json	✅ (via MCP)
Zed	register the MCP server in Zed settings	✅ (via MCP)
Any MCP-compatible client	point command at django-orm-lens-mcp, set DJANGO_ORM_LENS_ROOT	✅
Discoverable via MCP Registry	official Model Context Protocol server directory	✅
Plain terminal / CI	pip install django-orm-lens && django-orm-lens scan	✅

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.

🤔 How is this different?

	Django ORM Lens	django-extensions graph_models	django-schema-graph	Django Admin
Works without a bootable Django project	✅	❌	❌	❌
Zero-install (no graphviz, no server)	✅	❌	❌	❌
Sidebar tree inside the editor	✅	❌	❌	❌
Live ER diagram	✅	✅	✅	❌
Hover cards on ForeignKey	✅	❌	❌	❌
Split models/ package support	✅	⚠️	⚠️	✅
CLI for terminal / CI	✅	⚠️	❌	❌
MCP server for AI agents	✅	❌	❌	❌
Free & open-source	✅	✅	✅	✅

⚙️ 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
}

Setting	Type	Default	What it does
djangoOrmLens.excludeGlobs	string[]	See above	Glob patterns to skip when scanning
djangoOrmLens.autoRefresh	boolean	true	Rescan on models.py changes

🧭 Commands

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

Command	What it does
Django ORM Lens: Refresh	Force-rescan the workspace
Django ORM Lens: Show ER Diagram	Open the Mermaid ER diagram side-by-side
Django ORM Lens: Filter Models	Filter the tree by app / model / field name
Django ORM Lens: Clear Filter	Restore the full tree
Django ORM Lens: Jump to Model	Programmatic — triggered by tree clicks and hover cards

🗺️ 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

Next (v0.3.0)

• CodeLens above each class Model: N relations · N fields · Open ERD
• Edge labels on the diagram: CASCADE, SET_NULL, PROTECT, related_name
• Zoom + minimap + auto-layout inside the webview
• Named color themes (default / ocean / sunset / forest / dark)
• App / model toggle checkboxes to declutter huge schemas

Later

• Migration dependency graph
• ORM query autocomplete inside .filter()/.exclude()/.annotate()
• 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

Do you send any of my code to a server?

No. Every byte stays on your machine. The parser is pure TypeScript (extension) or pure Python (CLI). No LLM calls, no telemetry, no analytics, no error reporting. The Mermaid renderer runs inside VS Code's webview sandbox.

Does it work with Poetry / uv / conda / no venv at all?

Yes. The extension reads Python source directly — it does not import Django and does not care what package manager you use. The CLI requires Python 3.9+, but that is it.

My models are split across multiple files inside a models/ package. Does that work?

Yes, since v0.2.0. Both the extension and the CLI walk models/*.py alongside classic models.py.

Can I use it with DRF serializers, Wagtail, Oscar, or third-party base models?

Any class that looks like a Django model is picked up: subclasses of models.Model, abstract bases starting with Abstract, common mixins ending in Mixin, and known base names like TimeStampedModel or PolymorphicModel. Non-model classes (ModelAdmin, ModelSerializer, Form, View, Manager, …) are filtered out.

Which AI agents can use the MCP server?

Any MCP-compatible client — Cursor, Aider, Continue.dev, Zed, and any other tool that speaks the protocol. Just point command at the installed django-orm-lens-mcp binary. See the Integrations section.

Is there a JetBrains / PyCharm version?

Not yet. PyCharm's Django Structure tool window is already good, so the value delta is smaller. If enough people ask, it becomes worth doing.

🆘 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