MCP Django Shell

🚀 mcp-django-shell

A Model Context Protocol (MCP) server providing a stateful Django shell for AI assistants to interact with Django projects.

🚀 Quick Start

The mcp-django-shell is a Model Context Protocol (MCP) server that offers a stateful Django shell, enabling AI assistants to interact with Django projects. It sets up Django, maintains session state between calls, and allows the AI to write and execute Python code directly against your project.

✨ Features

• 🐚 One tool: 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.
• 🚀 Zero configuration: No schemas, no settings, just Django.
• 🤖 LLM-friendly: Designed for AI 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.

📦 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.

⚠️ Important Note

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.

💡 Usage Tip

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.

💻 Usage Examples

Basic Usage

Run the MCP server directly from your Django project directory:

python -m mcp_django_shell

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

# With debug logging
python -m mcp_django_shell --debug

Or using uv:

uv run -m mcp_django_shell

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:

python manage.py mcp_shell

Advanced Usage

Transport

The server supports multiple transport protocols:

# Default: STDIO
python -m mcp_django_shell

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

# SSE
python -m mcp_django_shell --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_shell": {
      "command": "python",
      "args": ["-m", "mcp_django_shell"],
      "cwd": "/path/to/your/django/project",
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings"
      }
    }
  }
}

Opencode

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

📚 Documentation

The MCP server comes with just two tools:

• 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, so the AI can work iteratively - exploring your models, testing queries, debugging issues.

🔧 Technical Details

Requirements

• Python 3.10, 3.11, 3.12, 3.13
• Django 4.2, 5.1, 5.2

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

📄 License

mcp-django-shell is licensed under the MIT license. See the file for more information.

Development

For detailed instructions on setting up a development environment and contributing to this project, see CONTRIBUTING.md.

For release procedures, see RELEASING.md.