Django MCP Server

mcp-django

PyPI - Python Version Django Version

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
Django 4.2, 5.1, 5.2

Installation

Choose the installation option that fits your use case:

Core

Provides read-only Django project exploration resources (django://project, django://apps, django://models).

# Read-only resources only - no shell access
pip install mcp-django

# Or with uv
uv add mcp-django

Shell

⚠️ DO NOT use in production!

Adds django_shell and django_reset tools for executing Python code.

# Includes shell tools for code execution
pip install "mcp-django[shell]"

# Or with uv
uv add "mcp-django[shell]"

Warning

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.

Caution

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.

All

# Currently same as [shell]
pip install "mcp-django[all]"

# Or with uv
uv add "mcp-django[all]"

Getting Started

Run the MCP server directly from your Django project directory:

python -m mcp_django

# With explicit settings module
python -m mcp_django --settings myproject.settings

# With debug logging
python -m mcp_django --debug

Or using uv:

uv run -m mcp_django

The server automatically detects DJANGO_SETTINGS_MODULE from your environment. You can override it with --settings or add to your Python path with --pythonpath.

There's also a Django management command if you prefer, but that requires adding mcp-django to INSTALLED_APPS:

python manage.py mcp

Transport

The server supports multiple transport protocols:

# Default: STDIO
python -m mcp_django

# HTTP
python -m mcp_django --transport http --host 127.0.0.1 --port 8000

# SSE
python -m mcp_django --transport sse --host 127.0.0.1 --port 8000

Client Configuration

Configure your MCP client using one of the examples below. The command is the same for all clients, just expressed in annoyingly different JSON soup.

Don't see your client? Submit a PR with setup instructions.

Claude Code

{
  "mcpServers": {
    "django": {
      "command": "python",
      "args": ["-m", "mcp_django"],
      "cwd": "/path/to/your/django/project",
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings"
      }
    }
  }
}

Opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "django": {
      "type": "local",
      "command": ["python", "-m", "mcp_django"],
      "enabled": true,
      "environment": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings"
      }
    }
  }
}

Features

mcp-django provides an MCP server with Django project exploration resources and optional shell access for LLM assistants. The base package offers safe, read-only resources while the shell extra adds stateful code execution capabilities.

It wouldn't be an MCP server README without a gratuitous list of features punctuated by emojis, so:

Core (mcp-django):

🔍 Project exploration - MCP resources for discovering apps, models, and configuration
🚀 Zero configuration - No schemas, no settings, just Django
🔒 Safe by default - Read-only resources, no code execution
🌐 Multiple transports - STDIO, HTTP, SSE support

Shell (mcp-django[shell]):

🐚 Stateful shell - django_shell executes Python code in your Django environment
🔄 Persistent state - Imports and variables stick around between calls
🧹 Reset when needed - django_reset clears the session when things get weird
🤖 LLM-friendly - Designed for LLM assistants that already know Python
📦 Minimal dependencies - Just FastMCP and Django (you already have Django)
🎯 Does one thing well - Runs code. That's it. That's the feature.

Inspired by Armin Ronacher's Your MCP Doesn't Need 30 Tools: It Needs Code.

Resources (mcp-django)

Read-only resources are provided for project exploration without executing code (note that resource support varies across MCP clients):

django://project - Python environment and Django configuration details
django://apps - All installed Django applications with their models
django://models - Detailed model information with import paths and field types

The idea is to give just enough information about the project to hopefully guide the LLM assistant and prevent needless shell exploration, allowing it to get straight to work.

Tools (mcp-django-shell)

When installed with the shell extra, two tools handle shell operations and session management:

django_shell - Execute Python code in a persistent Django shell session
django_reset - Reset the session, clearing all variables and imports

Imports and variables persist between calls within the shell tool, so the LLM can work iteratively - exploring your models, testing queries, debugging issues.

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.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables LLM assistants to explore Django project structure through read-only resources and optionally execute Python code in a stateful Django shell environment. Provides access to project configuration, app details, model information, and interactive development capabilities.

Related MCP Servers

MCP Package Docs Server
sammcj
A
security
A
license
A
quality
Facilitates LLMs to efficiently access and fetch structured documentation for packages in Go, Python, and NPM, enhancing software development with multi-language support and performance optimization.
Last updated -
31
76
MIT License
Code Research MCP Server
nahmanmate
A
security
A
license
A
quality
Facilitates searching and accessing programming resources across platforms like Stack Overflow, MDN, GitHub, npm, and PyPI, aiding LLMs in finding code examples and documentation.
Last updated -
6
39
AGPL 3.0
Project Explorer MCP Server
MausRundung362
A
security
A
license
A
quality
Provides tools for analyzing project structures, searching through codebases, managing dependencies, and performing file operations with advanced filtering capabilities.
Last updated -
6
24
1
MIT License
MCP Server Demo
DuttaAyush
-
security
F
license
-
quality
A demonstration server that provides tools for analyzing project structures and automatically generating comprehensive README files.
Last updated -

View all related MCP servers