Django Shell MCP Server

mcp-django-shell

A Model Context Protocol (MCP) server providing a stateful Django shell 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

1. Install the package from PyPI.
   python -m pip install mcp-django-shell # or if you like the new hotness uv add mcp-django-shell uv sync
2. (Optional) Add to your Django project's INSTALLED_APPS if you want to use the management command:
   DEBUG = ... if DEBUG: INSTALLED_APPS.append("mcp_django_shell")
   Note: You can now run mcp-django-shell without adding it to INSTALLED_APPS by using python -m mcp_django_shell directly. See below for more info.

Getting Started

Run the MCP server directly from your Django project directory:

Or using uv:

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-shell to INSTALLED_APPS:

Transport

The server supports multiple transport protocols:

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

Opencode

Features

mcp-django-shell provides an MCP server with a stateful Django shell for LLM assistants. It sets up Django, maintains session state between calls, and lets the LLM write and execute Python code directly against your project.

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

• 🐚 Stateful shell - django_shell executes Python code in your Django environment
• 🔍 Project exploration - MCP resources for discovering apps, models, and configuration
• 🔄 Persistent state - Imports and variables stick around between calls
• 🧹 Reset when needed - django_reset clears the session when things get weird
• 🚀 Zero configuration - No schemas, no settings, just Django
• 🤖 LLM-friendly - Designed for LLM assistants that already know Python
• 📦 Minimal dependencies - Just FastMCP and Django (you already have Django)
• 🌐 Multiple transports - STDIO, HTTP, SSE.. It has it all!
• 🎯 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

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

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-shell is licensed under the MIT license. See the LICENSE file for more information.