# Django Ai Boost

> A MCP server for Django applications, inspired by Laravel Boost.

- **Type:** MCP server
- **Install:** `agentstack add mcp-vintasoftware-django-ai-boost`
- **Verified:** Pending review
- **Seller:** [vintasoftware](https://agentstack.voostack.com/s/vintasoftware)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vintasoftware](https://github.com/vintasoftware)
- **Source:** https://github.com/vintasoftware/django-ai-boost

## Install

```sh
agentstack add mcp-vintasoftware-django-ai-boost
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Django AI Boost

A Model Context Protocol (MCP) server for developing Django applications, inspired by [Laravel Boost](https://github.com/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](https://gofastmcp.com/) 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](https://opencode.ai/))*

## Installation

### For End Users

```bash
# 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:

```bash
# 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:

```bash
# 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):**
```bash
export DJANGO_MCP_AUTH_TOKEN="your-secret-token"
django-ai-boost --settings myproject.settings --transport sse
```

**Or use CLI argument:**
```bash
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:

```bash
# 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))"
   ```

2. **Never commit tokens** to version control

3. **Use environment variables** in production (not CLI arguments)

4. **Rotate tokens periodically**

5. **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:**
```json
{
  "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:**
```bash
# 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](https://cursor.com/) 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:

```json
{
  "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](https://cursor.com/docs/context/mcp).

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

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

```json
{
"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"
    }
  }
 }
}
```

3. Click "Start" in the JSON
   

5. 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:

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

3. Restart VS Code or reload the Claude Code extension
4. 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`

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

```json
{
  "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`):

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

```bash
# 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](https://github.com/vintasoftware)
- **Source:** [vintasoftware/django-ai-boost](https://github.com/vintasoftware/django-ai-boost)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-vintasoftware-django-ai-boost
- Seller: https://agentstack.voostack.com/s/vintasoftware
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.