Django Ai Boost

Django AI Boost

A Model Context Protocol (MCP) server for developing Django applications, inspired by Laravel Boost. This server exposes Django project information through MCP tools, enabling AI assistants to better understand and interact with Django codebases.

Table of Contents

• [Features](#features)
• [Screenshots](#screenshots)
• [Installation](#installation)
• [For End Users](#for-end-users)
• [For Development](#for-development)
• [Usage](#usage)
• [Running the Server](#running-the-server)
• [Authentication](#authentication)
• [AI Tools Setup](#ai-tools-setup)
• [Cursor](#cursor)
• [Claude Desktop](#claude-desktop)
• [Github Copilot (VS Code)](#github-copilot-vs-code-extension)
• [Claude Code (VS Code)](#claude-code-vs-code-extension)
• [OpenAI ChatGPT Desktop](#openai-chatgpt-desktop-with-mcp)
• [Cline (VS Code)](#cline-vs-code-extension)
• [Zed Editor](#zed-editor)
• [Generic MCP Client](#generic-mcp-client)
• [Available Tools](#available-tools-and-prompts)
• [Example Usage](#example-usage-with-ai-assistants)
• [Development & Testing](#development--testing)
• [Troubleshooting](#troubleshooting)
• [Requirements](#requirements)
• [Contributing](#contributing)
• [License](#license)

Features

• Project Discovery: List models, URLs, and management commands
• Database Introspection: View schema, migrations, and relationships
• Configuration Access: Query Django settings with dot notation
• Log Reading: Access recent application logs with filtering
• Production-Ready Authentication: Bearer token authentication for secure deployments
• Read-Only: All tools are safe, read-only operations
• Fast: Built on FastMCP for efficient async operations

Screenshots

Click to view screenshots

Django AI Boost in Action

Django AI Boost MCP server providing Django project introspection through AI assistants (Example using OpenCode)

Installation

For End Users

# Using uv (recommended)
uv pip install django-ai-boost

# Or with pip
pip install django-ai-boost

For Development

If you want to contribute or run the latest development version:

# Clone the repository
git clone https://github.com/vinta/django-ai-boost.git
cd django-ai-boost

# Install uv if you haven't already
# On macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install dependencies (creates virtual environment automatically)
uv sync --dev

# Verify installation
uv run django-ai-boost --help

Usage

Running the Server

The server requires access to your Django project's settings:

# Set the Django settings module
export DJANGO_SETTINGS_MODULE=myproject.settings
django-ai-boost

# Or specify settings directly
django-ai-boost --settings myproject.settings

# Run with SSE transport (default is stdio, which doesn't use network ports)
django-ai-boost --settings myproject.settings --transport sse

# Run with SSE transport on a custom port (default port is 8000)
django-ai-boost --settings myproject.settings --transport sse --port 3000

# Run with SSE transport on custom host and port
django-ai-boost --settings myproject.settings --transport sse --host 0.0.0.0 --port 8080

Note: The stdio transport (default) communicates via standard input/output and does not use network ports. The --port and --host options only apply when using --transport sse.

Authentication

Django AI Boost supports bearer token authentication for secure production deployments when using SSE transport.

Quick Start

Set authentication token (recommended for production):

export DJANGO_MCP_AUTH_TOKEN="your-secret-token"
django-ai-boost --settings myproject.settings --transport sse

Or use CLI argument:

django-ai-boost --settings myproject.settings --transport sse --auth-token "your-secret-token"

How It Works

• Automatic Production Mode: When Django's DEBUG=False and using SSE transport, authentication is automatically required
• Token Precedence: Environment variable takes precedence over CLI argument for security
• Transport Support:
• ✅ SSE Transport: Full authentication support (HTTP-based)
• ❌ Stdio Transport: No authentication (local-only, trusted environments)
• Error on Mismatch: If you provide --auth-token with --transport stdio, the server will exit with an error to prevent false security assumptions

Production Deployment

When running in production (DEBUG=False) with SSE transport, you must provide an authentication token:

# This will fail without a token
django-ai-boost --settings myproject.production_settings --transport sse
# Error: Production mode detected but no authentication token provided

# This works
export DJANGO_MCP_AUTH_TOKEN="strong-secret-token"
django-ai-boost --settings myproject.production_settings --transport sse
# Authentication enabled with bearer token for SSE transport

Security Best Practices

1. Generate strong tokens:

``bash python -c "import secrets; print(secrets.token_urlsafe(32))" ``

1. Never commit tokens to version control

1. Use environment variables in production (not CLI arguments)

1. Rotate tokens periodically

1. Use HTTPS with a reverse proxy for external access

Client Configuration with Authentication

When using authentication, configure your MCP clients to include the token:

Cursor / Claude Desktop:

{
  "mcpServers": {
    "django-ai-boost": {
      "command": "django-ai-boost",
      "args": ["--settings", "myproject.settings", "--transport", "sse"],
      "env": {
        "DJANGO_MCP_AUTH_TOKEN": "your-secret-token",
        "DJANGO_SETTINGS_MODULE": "myproject.settings",
        "PYTHONPATH": "/path/to/your/django/project"
      }
    }
  }
}

Testing with curl:

# Without auth - fails
curl http://127.0.0.1:8000/sse

# With correct token - works
curl -H "Authorization: Bearer your-secret-token" http://127.0.0.1:8000/sse

Troubleshooting Authentication

"Production mode detected but no authentication token provided"

• Set DJANGO_MCP_AUTH_TOKEN environment variable or use --auth-token

"Authentication token provided but transport is 'stdio'"

• This is now an error that stops the server from starting
• Authentication only works with --transport sse
• Either use --transport sse with your token, or remove the --auth-token argument for stdio

"Running in production mode with stdio transport"

• This is OK for local/trusted environments, but stdio has no authentication capability
• For remote access, use --transport sse with authentication

AI Tools Setup

Cursor

Cursor is a popular AI-powered code editor with built-in MCP support.

1. Open Cursor Settings (Cmd/Ctrl + Shift + J)
2. Navigate to the "Tools & MCP" section
3. Add the Django AI Boost server configuration:

{
  "mcpServers": {
    "django-ai-boost": {
      "command": "django-ai-boost",
      "args": ["--settings", "myproject.settings"],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings",
        "PYTHONPATH": "/path/to/your/django/project"
      }
    }
  }
}

Note: Replace /path/to/your/django/project with the actual path to your Django project root directory.

For more information, see the Cursor MCP documentation.

Claude Desktop

Add to your Claude Desktop configuration:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "django": {
      "command": "django-ai-boost",
      "args": ["--settings", "myproject.settings"],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings",
        "PYTHONPATH": "/path/to/your/django/project"
      }
    }
  }
}

Note: Make sure to replace /path/to/your/django/project with the actual path to your Django project root directory.

Github Copilot (VS Code Extension)

1. Install the Github Copilot Chat extension from VS Code marketplace
2. Create or edit .vscode/mcp.json in your Django project root:

{
"inputs": [
  // The "inputs" section defines the inputs required for the MCP server configuration.
  {
    "type": "promptString"
  }
],
"servers": {
  // The "servers" section defines the MCP servers you want to use.
  "django-ai-boost": {
    "command": "uv",
    "args": ["run", "django-ai-boost", "--settings", "myproject.settings"],
    "env": {
      "DJANGO_SETTINGS_MODULE": "myproject.settings"
    }
  }
 }
}

1. Click "Start" in the JSON

1. Github Copilot Code will automatically connect to the MCP server when you start a conversation in "Agent" mode.

Claude Code (VS Code Extension)

1. Install the Claude Code extension from VS Code marketplace
2. Create or edit .mcp.json in your Django project root:

{
  "mcpServers": {
    "django-ai-boost": {
      "command": "uv",
      "args": ["run", "django-ai-boost", "--settings", "myproject.settings"],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings"
      }
    }
  }
}

1. Restart VS Code or reload the Claude Code extension
2. Claude Code will automatically connect to the MCP server when you start a conversation

OpenAI ChatGPT Desktop with MCP

OpenAI ChatGPT Desktop supports MCP servers. Add to your configuration file:

• macOS: ~/Library/Application Support/OpenAI/ChatGPT/config.json
• Windows: %APPDATA%\OpenAI\ChatGPT\config.json

{
  "mcpServers": {
    "django": {
      "command": "django-ai-boost",
      "args": ["--settings", "myproject.settings"],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings"
      }
    }
  }
}

Cline (VS Code Extension)

1. Install the Cline extension from VS Code marketplace
2. Open Cline settings (Cmd/Ctrl + Shift + P → "Cline: Open Settings")
3. Add MCP server configuration in the MCP Servers section:

{
  "django": {
    "command": "django-ai-boost",
    "args": ["--settings", "myproject.settings"],
    "env": {
      "DJANGO_SETTINGS_MODULE": "myproject.settings"
    }
  }
}

Zed Editor

Add to your Zed MCP configuration (~/.config/zed/mcp.json):

{
  "servers": {
    "django": {
      "command": "django-ai-boost",
      "args": ["--settings", "myproject.settings"],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings"
      }
    }
  }
}

Generic MCP Client

For any MCP-compatible client, you can run the server manually:

# Standard I/O transport (default, no network port)
django-ai-boost --settings myproject.settings

# Server-Sent Events transport (default: 127.0.0.1:8000)
django-ai-boost --settings myproject.settings --transport sse

# SSE transport with custom port
django-ai-boost --settings myproject.settings --transport sse --port 3000

# SSE transport with custom host and port
django-ai-boost --settings myproject.settings --transport sse --host 0.0.0.0 --port 8080

Available Tools and Prompts

Tools

1. application_info

Get Django and Python versions, installed apps, middleware, database engine, and debug mode status.

2. get_setting

Retrieve any Django setting using dot notation (e.g., DATABASES.default.ENGINE).

3. list_models

List all Django models with fields, types, max_length, null/blank status, and relationships.

Arguments:

• app_labels: Optional list of app labels to filter (e.g., ["blog", "auth"]). If not provided, returns all models.

Note: For large projects, some MCP clients (like PyCharm) may truncate output due to display limits. Use the app_labels parameter to filter by specific apps to avoid truncation. See [Troubleshooting](#troubleshooting) for more details.

4. list_urls

Show all URL patterns with names, patterns, and view handlers (including nested includes).

5. database_schema

Get complete database schema including tables, columns, types, indexes, and foreign keys.

6. list_migrations

View all migrations per app with their applied/unapplied status.

7. list_management_commands

List all available manage.py commands with their source apps.

8. get_absolute_url

Get the absolute URL for a specific model instance. Requires the model to have a get_absolute_url() method defined.

Arguments:

• app_label: The Django app label (e.g., "blog")
• model_name: The model name (e.g., "Post")
• pk: The primary key of the instance

9. reverse_url

Reverse a named URL pattern to get its actual URL path. Supports both positional args and keyword arguments.

Arguments:

• url_name: The URL pattern name (e.g., "post_detail", "admin:index")
• args: Optional list of positional arguments
• kwargs: Optional dict of keyword arguments

10. query_model

Query a Django model with read-only operations using the Django ORM manager. This tool allows safe querying of any Django model with filtering, ordering, and pagination.

Arguments:

• app_label: The Django app label (e.g., "blog")
• model_name: The model name (e.g., "Post")
• filters: Optional dict of field lookups (e.g., {"status": "published", "featured": true})
• order_by: Optional list of fields to order by (e.g., ["-created_at", "title"])
• limit: Maximum number of results to return (default: 100, max: 1000)

Returns:

• Total count of matching objects
• Number of results returned
• List of model instances as dictionaries with all field values
• For foreign keys, includes both the ID and string representation

Example Queries:

• Get all published posts: filters={"status": "published"}
• Get featured posts ordered by date: filters={"featured": true}, order_by=["-created_at"]
• Get recent posts with limit: order_by=["-created_at"], limit=10

11. run_check

Run Django's system checks to identify potential issues in models, settings, and deployment configuration.

Arguments:

• app_labels: Optional list of app labels to check
• tags: Optional list of check tags (e.g., "models", "compatibility")
• deploy: Include deployment checks when true
• fail_level: Minimum severity ("CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG")
• databases: Optional list of database aliases to include

12. read_recent_logs

Read recent lines from file-based log handlers configured in LOGGING.handlers.

Arguments:

• lines: Number of lines to return per file (default: 100, configurable via DJANGO_MCP_MAX_LOG_LINES env var)
• handler_name: Optional handler name to read from a single file handler

> Note: This tool reads only file-based handlers (*FileHandler classes). If your project logs to the console only, configure a FileHandler in your Django LOGGING settings so the AI can access log output. Example: > > ``python > LOGGING = { > "version": 1, > "handlers": { > "file": { > "class": "logging.FileHandler", > "filename": "django.log", > }, > }, > "root": {"handlers": ["file"], "level": "INFO"}, > } > ``

Prompts

MCP prompts provide reusable message templates to help guide interactions with AI assistants.

1. search_django_docs

Generate a formatted prompt to help search for specific topics in Django documentation.

Arguments:

• topic: The Django topic or feature to search for (e.g., "models", "queryset", "migrations", "authentication")

Returns: A formatted prompt that includes:

• The current Django version being used
• Direct links to the appropriate version of Django documentation
• Guidance on what information to look for
• Request for best practices a

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vintasoftware
• Source: vintasoftware/django-ai-boost
• License: MIT

Install and usage instructions live in the source repository linked above.