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!

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.