django-native-mcp

Ein kleines, Django-natives MCP-Framework für Anwendungen und Tool-Registrierung, inspiriert von Celery. Es delegiert Protokollbehandlung, Schemas, Validierung, Serialisierung, stdio und Streamable HTTP an das offizielle mcp Python SDK.

Dies ist kein weiterer Wrapper um FastMCP; die Abhängigkeiten sind ausschließlich das native Python SDK

Installation

pip install django-native-mcp

Fügen Sie die Anwendung und ihre Konfiguration hinzu:

# settings.py

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

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

Erstellen Sie die Anwendung:

# config/mcp.py

from django_native_mcp import MCP

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

Deklarieren Sie Tools explizit in installierten Django-Apps:

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

Der registrierte Name lautet orders.get_order, wobei das Label der Django-Anwendung verwendet wird.

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

Tools müssen async def verwenden. Das Framework fügt keine impliziten Threads oder sync_to_async hinzu.

Related MCP server: django-mcp

Direkte Anwendungs-Tools

from django_native_mcp import MCP

app = MCP("backend")


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

@app.tool bindet sofort an eine Anwendung. @shared_tool bleibt anwendungsunabhängig, bis es durch die Autodiscovery gebunden wird.

Streamable HTTP mit Django

Die offizielle ASGI-App des SDK kann allein bereitgestellt werden:

application = app.asgi_app()

Oder leiten Sie /mcp an MCP und alles andere an Django weiter:

# 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",
)

Der Dispatcher leitet den ASGI-Lifespan an die offizielle MCP-Anwendung weiter, sodass ihr Transportlebenszyklus vom äußeren ASGI-Server gestartet und gestoppt wird.

Testen

Verwenden Sie den dünnen Wrapper um den offiziellen In-Process-Client:

from django_native_mcp.testing import MCPTestClient


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

End-to-End-Beispiel

Das Verzeichnis example/ enthält ein ausführbares Django-Projekt, das das integrierte Auth-User-Modell, einen Streamable-HTTP-MCP-Endpunkt und einen eigenständigen OpenAI-Responses-API-Client verwendet, der das Django-Tool über MCP entdeckt und aufruft.

Architektur

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

Die Registrierung ist prozesslokal und wird schreibgeschützt, sobald ihr offizieller Server erstellt wird. Jeder Worker baut beim Start dieselbe Registrierung aus dem Quellcode auf.

Nicht-Ziele

Dieses Paket ist keine MCP-Protokollimplementierung, kein ORM-zu-MCP-Generator, kein REST/DRF-Adapter, kein Celery-Ersatz, keine Hintergrundwarteschlange und kein KI-Agenten-Framework. Es legt Django-Modelle nicht automatisch offen und leitet keine Berechtigungen aus ihnen ab.

Lizenz

MIT