This MCP server provides Django project exploration resources and an optional stateful shell for interacting with Django projects via an LLM. It helps you inspect apps, models, routes, and settings, while offering convenient, isolated execution of Python in a Django context for development use only.

How to use

Connect with an MCP client to start exploring a Django project. You can run the server locally to inspect project structure, models, settings, and routes, or expose it over HTTP/SSE for remote access. The server offers a stateless Python execution shell so your LLM can run Python snippets against your Django project in a controlled environment.

How to install

Prerequisites: you need Python and a runtime environment for the MCP client that you will use to connect to the server.

pip install mcp-django

# Or, if you manage MCPs via uv (Unified Virtual Environment)
uv add mcp-django

Then run the MCP server

Run the MCP server directly from your Django project directory. The server will detect your Django settings automatically from the environment unless you override them.

python -m mcp_django

uv run -m mcp_django

Override settings and debugging

If you need to specify Django settings explicitly, pass them on the command line. This is useful when your environment does not automatically expose DJANGO_SETTINGS_MODULE.

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

Management command

If you add the MCP server to INSTALLED_APPS, you can run it as a Django management command inside your project. This ensures the server runs with your project’s settings.

python manage.py mcp

Docker

You can run mcp-django as a separate Compose service using HTTP transport. This connects your MCP client (running on your host) to the Django project inside containers.

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

## Transport options

The server supports multiple transport protocols for MCP connections.

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. The following examples show local development (stdin/stdout) and remote HTTP transport.

Local development (Opencode): use a local type with the command to run the MCP server.

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

## Remote development (Docker/HTTP/SSE)

For Docker development with HTTP transport, use a remote configuration that points to the HTTP endpoint.

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

## Notes and safety

⚠️ For development use only. Do not enable in production, as the server can execute arbitrary Python code inside your Django project context.

## Security considerations

This MCP server provides access to run code within your Django project environment. Use it only in trusted development contexts and ensure you do not expose production data or credentials to LLMs or external clients.

## Troubleshooting

If the server fails to start, verify that your environment can locate Django settings, that the port is not in use, and that the Python environment has the required dependencies installed.

## Available tools

### get\_project\_info

Get comprehensive project information including Python environment and Django configuration.

### get\_setting

Retrieve a Django setting value by key.

### list\_apps

List all installed Django applications with their models.

### list\_models

Get detailed information about Django models with optional filtering by app or scope.

### list\_routes

Inspect Django URL routes with filters for HTTP methods, route names, or patterns.

### execute\_command

Execute Django management commands with arguments and options.

### list\_commands

List all available Django management commands with their originating apps.

### execute

Execute Python code in a stateless Django shell.

### export\_history

Export session history as a Python script.

### clear\_history

Clear the current session history for a fresh start.

### get\_grid

Get a comparison grid from djangopackages.org for Django packages.

### get\_package

Get detailed information about a specific Django package.

### search

Search djangopackages.org for third-party Django packages.