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 5.2, 6.0

Installation

pip install mcp-django

# Or with uv
uv add mcp-django

Getting Started

⚠️ DO NOT use in production!

> [!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.

Run the MCP server directly from your Django project directory:

python -m mcp_django

# Or with 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`:

python -m mcp_django --settings myproject.settings --debug

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:

python manage.py mcp

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

# compose.yml
services:
  app:
    # your existing Django app service

  mcp:
    build: .
    command: python -m mcp_django --transport http --host 0.0.0.0 --port 8000
    environment:
      DJANGO_SETTINGS_MODULE: myproject.settings
    ports:
      - "8001:8000"

Then configure your MCP client to connect to `http://localhost:8001/mcp` (see Client Configuration below).

Transport Options

The server supports multiple transport protocols:

# STDIO (default, for local development)
python -m mcp_django

# HTTP (for Docker or remote access)
python -m mcp_django --transport http --host 127.0.0.1 --port 8000

# SSE (for Docker or remote access)
python -m mcp_django --transport sse --host 127.0.0.1 --port 8000

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:

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

For Docker development, use `type: remote` with the URL:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "django": {
      "type": "remote",
      "url": "http://localhost:8001/mcp",
      "enabled": true
    }
  }
}

Claude Code

For local development, use the command configuration:

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

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 - `shell` executes 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

djangopackages.org

Tools

Project

Management

Shell

djangopackages.org

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.