Skip to content

Getting Started

This guide walks you through installing, configuring, and running drf-mcp-docs with your Django REST Framework project.

Prerequisites

  • Python 3.10+
  • Django 4.2+
  • Django REST Framework 3.14+
  • A schema generator (recommended: drf-spectacular)

Installation

Install drf-mcp-docs from PyPI:

pip install drf-mcp-docs

For the best experience, install with drf-spectacular (provides the most complete OpenAPI schemas):

pip install drf-mcp-docs[spectacular]

Or with drf-yasg:

pip install drf-mcp-docs[yasg]

If you don't install either, drf-mcp-docs falls back to DRF's built-in schema generation, which produces more limited output.

Configuration

1. Add to INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    # ...
    'rest_framework',
    'drf_spectacular',  # or 'drf_yasg' — if using one
    'drf_mcp_docs',
]

2. Configure your schema generator

If using drf-spectacular:

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

3. (Optional) Customize drf-mcp-docs settings

All settings have sensible defaults. You only need to add this if you want to customize behavior:

DRF_MCP_DOCS = {
    'SERVER_NAME': 'my-project-api',
    'CACHE_SCHEMA': not DEBUG,
}

See Configuration for all available settings.

Running the MCP Server

python manage.py runmcpserver --transport stdio

This is the most common setup. Your AI tool (Claude Code, Cursor, etc.) launches this command as a subprocess and communicates via stdin/stdout.

streamable-http transport (for network access)

python manage.py runmcpserver --transport streamable-http --host 0.0.0.0 --port 8100

Use this when the AI tool connects over the network.

Development mode (auto-reload)

python manage.py runmcpserver --transport streamable-http --port 8100 --reload

The --reload flag uses Django's autoreload to restart the server when source files change. Only supported with streamable-http transport.

Validate configuration

Before running, you can check that everything is set up correctly:

python manage.py checkmcpconfig

This validates settings, tests adapter detection, and verifies schema generation.

Connecting AI Tools

Claude Code

Add to your Claude Code MCP configuration (~/.claude.json):

{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["manage.py", "runmcpserver", "--transport", "stdio"],
      "cwd": "/path/to/your/django/project"
    }
  }
}

If you use a virtual environment:

{
  "mcpServers": {
    "my-api": {
      "command": "/path/to/venv/bin/python",
      "args": ["manage.py", "runmcpserver", "--transport", "stdio"],
      "cwd": "/path/to/your/django/project"
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["manage.py", "runmcpserver", "--transport", "stdio"],
      "cwd": "/path/to/your/django/project"
    }
  }
}

VS Code (with MCP extension)

Add to your VS Code settings or workspace .vscode/mcp.json:

{
  "servers": {
    "my-api": {
      "command": "python",
      "args": ["manage.py", "runmcpserver", "--transport", "stdio"],
      "cwd": "/path/to/your/django/project"
    }
  }
}

Other MCP clients

For any MCP client that supports streamable-http:

  1. Start the server: python manage.py runmcpserver --transport streamable-http --port 8100
  2. Connect to: http://localhost:8100/mcp/

Verify It Works

After connecting, ask your AI agent:

"Show me an overview of the API"

The agent should read the api://overview resource and return information about your API — title, version, endpoints count, authentication methods, etc.

Try more:

"What endpoints are available for users?"

"Generate a fetch function to create a new product"

"Show me the Product schema"

Next Steps