django-native-mcp

Un pequeño framework para aplicaciones MCP nativas en Django y de registro de herramientas, inspirado en Celery. Delega el manejo de protocolos, esquemas, validación, serialización, stdio y Streamable HTTP al SDK oficial de Python mcp.

Este no es otro wrapper alrededor de FastMCP; las dependencias son solo el SDK nativo de Python

Instalación

pip install django-native-mcp

Añade la aplicación y su configuración:

# settings.py

INSTALLED_APPS = [
    # ...
    "django_native_mcp",
]

DJANGO_NATIVE_MCP = {
    "APP": "config.mcp:app",
}

Crea la aplicación:

# config/mcp.py

from django_native_mcp import MCP

app = MCP("backend")
app.autodiscover_tools()

Declara herramientas explícitamente en las aplicaciones Django instaladas:

# orders/mcp.py

from django_native_mcp import shared_tool

from .models import Order


@shared_tool
async def get_order(order_id: int) -> dict:
    """Get an order."""
    order = await Order.objects.aget(pk=order_id)
    return {"id": order.pk, "status": order.status}

El nombre registrado es orders.get_order, usando la etiqueta de la aplicación de Django.

python manage.py mcp_list
python manage.py mcp_inspect orders.get_order
python manage.py mcp_call orders.get_order '{"order_id": 1}'
python manage.py mcp_serve --transport stdio

Las herramientas deben usar async def. El framework no añade hilos implícitos ni sync_to_async.

Related MCP server: django-mcp

Herramientas directas de la aplicación

from django_native_mcp import MCP

app = MCP("backend")


@app.tool(name="system.health")
async def health() -> dict:
    return {"ok": True}

@app.tool se vincula inmediatamente a una aplicación. @shared_tool permanece independiente de la aplicación hasta que el autodescubrimiento lo vincula.

Streamable HTTP con Django

La aplicación ASGI del SDK oficial puede servirse por sí sola:

application = app.asgi_app()

O enruta /mcp a MCP y todo lo demás a Django:

# config/asgi.py

import os

from django.core.asgi import get_asgi_application

from django_native_mcp.asgi import MCPApplication

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
django_application = get_asgi_application()

# Import the MCP app only after Django's application registry is ready.
from config.mcp import app as mcp_app

application = MCPApplication(
    django=django_application,
    mcp=mcp_app,
    mcp_path="/mcp",
)

El dispatcher reenvía el ciclo de vida ASGI a la aplicación MCP oficial, de modo que el servidor ASGI externo inicia y detiene su ciclo de vida de transporte.

Pruebas

Usa el envoltorio ligero alrededor del cliente oficial del proceso:

from django_native_mcp.testing import MCPTestClient


async with MCPTestClient(app) as client:
    result = await client.call_tool("orders.get_order", {"order_id": 1})

Ejemplo de extremo a extremo

El directorio example/ contiene un proyecto de Django ejecutable con la autenticación integrada de User, una endpoint Streamable HTTP para MCP y un cliente independiente de la OpenAI Responses API que descubre y llama la herramienta de Django a través de MCP.

Arquitectura

Django apps / mcp.py
        ↓
shared_tool → ToolDefinition → ToolRegistry → MCP
                                              ↓
                                      official MCPServer
                                      ↙              ↘
                                   stdio       Streamable HTTP

El registro es local respecto al proceso y se vuelve de solo lectura cuando se crea su servidor oficial. Cada worker construye el mismo registro a partir del código fuente durante el arranque.

Objetivos no contemplados

Este paquete no es una implementación del protocolo MCP, ni un generador de ORM a MCP, ni un adaptador REST/DRF, ni un sustituto de Celery, ni una cola en segundo plano, ni un framework de agentes de IA. No expone automáticamente los modelos de Django y no infiere permisos a partir de ellos.

Licencia

MIT