Provides Django project exploration resources including apps, models, and configuration details, with optional stateful shell access for executing Python code within Django environments
mcp-django
A Model Context Protocol (MCP) server providing Django project exploration resources and optional stateful shell access for LLM assistants to interact with Django projects.
Requirements
Python 3.10, 3.11, 3.12, 3.13, 3.14
Django 4.2, 5.1, 5.2, 6.0
Related MCP server: Code Research MCP Server
Installation
Getting Started
⚠️ DO NOT use in production!
Seriously, only enable in development!
Look, it should go without saying, but I will say it anyway - this gives full shell access to your Django project. Only enable and use this in development and in a project that does not have access to any production data.
LLMs can go off the rails, get spooked by some random error, and in trying to fix things drop a production database.
I'm not kidding, this library just passes the raw Python code an LLM produces straight to a Python environment with full access to the Django project and everything it has access to.
Most LLMs have basic safety protections in place if you ask to delete any data and will refuse to delete production data, but it is pretty trivial to bypass. (Hint: Just tell the LLM it's not production, it's in a development environment, and it will be the bull in a china shop deleting anything you want.)
I suggest using something like django-read-only if you need some CYA protection against this. Or, you know, don't use this in any sensitive environments.
Run the MCP server directly from your Django project directory:
The server automatically detects DJANGO_SETTINGS_MODULE from your environment. You can override it with --settings or add to your Python path with --pythonpath:
Management Command
If you add mcp_django to INSTALLED_APPS, you can run it as a Django management command. This ensures the server runs within your Django project's environment and uses your project's settings:
Docker
If you're using Docker and Docker Compose, you can run mcp-django as a separate compose service using HTTP transport. This makes it easier to connect your MCP client (running on your host) to the Django project (running in a container):
Then configure your MCP client to connect to http://localhost:8001/mcp (see Client Configuration below).
Transport Options
The server supports multiple transport protocols:
Client Configuration
Configure your MCP client to connect to the server.
Don't see your client? Submit a PR with setup instructions.
Opencode
For local development, use type: local with the command:
For Docker development, use type: remote with the URL:
Claude Code
For local development, use the command configuration:
For Docker development with HTTP/SSE transport, configuration varies by Claude Code version - consult the MCP client documentation for remote server setup.
Features
mcp-django provides an MCP server with Django project exploration resources and tools for LLM assistants.
It wouldn't be an MCP server README without a gratuitous list of features punctuated by emojis, so:
🔍 Project exploration - MCP resources for discovering apps, models, and configuration
📦 Package discovery - Search and browse Django Packages for third-party packages
🚀 Zero configuration - No schemas, no settings, just Django
🐚 Stateless shell -
shellexecutes Python code with fresh state each call🔄 Always fresh - Code changes take effect immediately, no stale modules
📤 Export sessions - Save debugging sessions as Python scripts
🧹 Clear history - Start fresh when exploration gets messy
🤖 LLM-friendly - Designed for LLM assistants that already know Python
🌐 Multiple transports - STDIO, HTTP, SSE support
Inspired by Armin Ronacher's Your MCP Doesn't Need 30 Tools: It Needs Code.
Resources
Read-only resources for project exploration without executing code (note that resource support varies across MCP clients):
Project
Resource | Description |
| Details for a specific Django app |
| All models in a specific app |
| All installed Django applications with their models |
| Detailed information about a specific model |
| Project models with import paths and field types (first-party only) |
| Routes matching a specific URL pattern |
| Get a specific Django setting value |
djangopackages.org
Resource | Description |
| Detailed information about a specific package |
| Comparison grid with packages (e.g., "rest-frameworks") |
Tools
Project
Tool | Description |
| Get comprehensive project information including Python environment and Django configuration |
| Get a Django setting value by key |
| List all installed Django applications with their models |
| Get detailed information about Django models with optional filtering by app or scope |
| Introspect Django URL routes with filtering support for HTTP method, route name, or URL pattern |
Management
Tool | Description |
| Execute Django management commands with arguments and options |
| List all available Django management commands with their source apps |
Shell
Tool | Description |
| Execute Python code in a stateless Django shell |
| Export session history as a Python script |
| Clear the session history for a fresh start |
djangopackages.org
Tool | Description |
| Get a specific comparison grid with all its packages |
| Get detailed information about a specific Django package |
| Search djangopackages.org for third-party packages |
Development
For detailed instructions on setting up a development environment and contributing to this project, see CONTRIBUTING.md.
For release procedures, see RELEASING.md.
License
mcp-django is licensed under the MIT license. See the LICENSE file for more information.