django-admin-fastmcp

Eine wiederverwendbare Django-App, die die Django-Admin-Oberfläche als MCP-Server bereitstellt, basierend auf FastMCP.

Jeder Tool-Aufruf läuft als der Staff-Benutzer, dem das Bearer-Token gehört. Jeder Tool-Aufruf fragt zuerst den ModelAdmin um Erlaubnis. Ein Superuser kann alles tun, was ein Superuser im Admin tun kann. Ein Staff-Benutzer kann genau das tun, was dieser Staff-Benutzer im Admin tun kann, und nicht mehr.

SPEC.md ist die vollständige Spezifikation.

So funktioniert es

Drei Regeln definieren das Paket:

1. Kein paralleles Berechtigungssystem. Die Autorisierung delegiert an die ModelAdmin-Methoden: has_view_permission, has_add_permission, has_change_permission, has_delete_permission, get_queryset, get_readonly_fields und get_actions. Eine get_queryset-Überschreibung, die Zeilen verbirgt, verbirgt sie auch vor MCP.

2. Keine parallele Datenoberfläche. Schreibvorgänge laufen über das eigene ModelForm des Admins und save_model und protokollieren dann einen LogEntry. Die Admin-Verlaufsseite bleibt wahrheitsgemäß.

3. Fail closed. Jede unaufgelöste Suche, fehlender ModelAdmin, unbekannte Aktion, unbekanntes Feld und unbekanntes Tool verweigert den Aufruf.

Installation

uv add django-admin-fastmcp

Fügen Sie die App zu Ihren Einstellungen hinzu:

INSTALLED_APPS = [
    ...,
    "django.contrib.admin",
    "django_admin_fastmcp",
]

ADMIN_FASTMCP = {
    "SERVER_NAME": "acme-admin",
    "EXCLUDE_MODELS": ("auth.Permission", "auth.Group"),
    "WRITABLE_MODELS": (),          # empty means no writes at all
}

Mounten Sie die OAuth-Endpunkte auf derselben Site wie den Admin:

# urls.py
urlpatterns = [
    # RFC 8414 fixes this one at the site root.
    path("", include("django_admin_fastmcp.well_known_urls")),
    # This prefix is yours to choose. Match it to the path in MCP_URL.
    path("admin/mcp/", include("django_admin_fastmcp.urls")),
    path("admin/", admin.site.urls),
]

Das Paket legt kein Präfix fest. Jede URL, die das Metadaten-Dokument bewirbt, stammt von reverse(), sodass ein Projekt, das die Endpunkte unter /backoffice/oauth/ mountet, dies in der Discovery erhält und Clients dem folgen. Zwei Regeln: Das Well-Known-Dokument gehört an die Wurzel, weil ein Client seine URL vom Issuer ableitet, und die Endpunkte sollten auf derselben Site wie der Admin liegen, weil die Zustimmungsseite auf dem Admin-Session-Cookie reitet.

Wenden Sie die Migrationen an:

python manage.py migrate django_admin_fastmcp

Sonst nichts. Keine Pro-Modell-Registrierung, kein Mixin, keine Dekorateure. Der Server stellt genau das bereit, was der Admin bereits bereitstellt.

Einen Client verbinden

Starten Sie den Server (siehe Bereitstellung) und registrieren Sie ihn dann:

# Claude Code
claude mcp add --transport http acme-admin https://<host>/admin/mcp

Verwenden Sie den Pfad ohne abschließenden Schrägstrich. /admin/mcp/ antwortet mit einer 307-Weiterleitung auf /admin/mcp, und nicht jeder Client folgt einer Weiterleitung bei POST.

Kein Token, kein Header. Der erste Aufruf startet den standardmäßigen MCP-OAuth-Ablauf:

1. Der Client öffnet Ihren Browser auf der Autorisierungsseite auf der Django-Site.

2. Ihr Admin-Session-Cookie identifiziert Sie. Wenn Sie abgemeldet sind, erscheint zuerst die normale Admin-Anmeldung.

3. Eine Zustimmungsseite zeigt den Client-Namen und was die Genehmigung bedeutet. Sie stimmen zu.

4. Der Client erhält seine Tokens und verbindet sich. Er erneuert sie selbstständig.

Jeder MCP-Client, der streambares HTTP mit OAuth spricht, funktioniert auf die gleiche Weise, zum Beispiel Cursor oder ein FastMCP-Client.

Regeln zum Zugriff:

• Jeder Staff-Benutzer kann einen Client autorisieren, nur für sich selbst.

• Eine Genehmigung handelt mit Ihren eigenen Admin-Berechtigungen, niemals mehr. Es gibt kein separates Berechtigungssystem: Wer ein Modell im Admin ändern darf, darf es auch über MCP ändern, wenn der Server dieses Modell in WRITABLE_MODELS auflistet.

• Refresh-Tokens laufen nach REFRESH_TOKEN_TTL_DAYS (Standard 90) ab, sodass eine erneute Zustimmung so oft erfolgt. Der Widerruf ist eine Admin-Aktion auf der Genehmigungs-Changelist.

Tools

Elf generische Tools, gemountet unter dem Namensraum admin, sodass die Drahtnamen admin_list_models usw. sind. Jedes nimmt model als "app_label.ModelName" entgegen. Die Tool-Liste ist statisch. Was pro Benutzer variiert, ist, was jedes Tool diesem Benutzer erlaubt zu sehen und zu tun.

Lesen

Schreiben

Schreib-Tools benötigen das Modell in WRITABLE_MODELS; Ihre eigenen Admin-Berechtigungen entscheiden den Rest, pro Modell und pro Objekt. Ein Modell außerhalb der Liste verweigert jeden Schreibvorgang und jede Aktion, wer auch immer aufruft. Lassen Sie sensible Modelle außen vor, z. B. ein Ereignisprotokoll, und kein MCP-Client kann jemals darauf schreiben.

Jede zurückgegebene Zeile trägt pk als Zeichenfolge und eine admin_url, sodass ein Agent einer Person einen Link in den echten Admin übergeben kann.

Einstellungen

Alle Schlüssel leben im ADMIN_FASTMCP-Wörterbuch. Ein unbekannter Schlüssel ist ein Fehler beim Start.

Setzen Sie SITE_URL und MCP_URL für jede echte Bereitstellung. MCP_URL ist die einzige Quelle für drei Dinge, die übereinstimmen müssen: den Pfad, auf dem der Endpunkt bereitgestellt wird, die resource, die die Discovery bewirbt, und die Zielgruppe, an die jedes Token gebunden ist. Sein Pfad standardmäßig auf /admin/mcp. Ein Startcheck verweigert eine MCP_URL ohne Pfad, weil dann die gesamte Herkunft als geschützte Ressource beworben würde.

Pro-ModelAdmin-Einstellungen

Setzen Sie diese auf einer ModelAdmin-Klasse, kein Mixin erforderlich:

class InvoiceAdmin(admin.ModelAdmin):
    mcp_expose = False                     # hide this model from MCP entirely
    mcp_fields = ("number", "total")       # allowlist of serialized fields
    mcp_exclude_fields = ("internal_note",)  # denylist of serialized fields

REDACT_FIELDS gewinnt über mcp_fields. Ein Passwortfeld explizit aufzulisten, offenbart es nicht.

Sicherheit

Ein Admin-MCP-Server für einen Superuser ist eine Remote-Shell über der Produktionsdatenbank, gesteuert von einem Sprachmodell. Die Leitplanken:

• WRITABLE_MODELS ist standardmäßig leer, sodass kein Modell Schreibvorgänge akzeptiert, bis die Bereitstellung es benennt. Alles andere sind Ihre gewöhnlichen Django-Berechtigungen, die über den ModelAdmin bei jedem Aufruf abgefragt werden.

• Zugriffstokens sind kurzlebig. Es werden nur gesalzene Hashes gespeichert, sodass eine durchgesickerte Datenbankzeile nicht wiederverwendet werden kann.

• delete_object und run_action zeigen standardmäßig eine Vorschau und ändern nichts, bis confirm=True.

• Jede Mutation protokolliert einen LogEntry, der dem Benutzer der Genehmigung zugeordnet ist, mit dem Client-Namen in der Änderungsnachricht, z. B. "Status geändert. Über MCP (Client: Claude Code).". Ein Schreibvorgang, der keinen LogEntry protokollieren kann, wird zurückgerollt.

• Die eigenen Modelle des Pakets, sessions.Session und authtoken.Token werden niemals freigegeben, was auch immer die Einstellungen sagen.

• Halten Sie auth.Permission und auth.Group aus WRITABLE_MODELS heraus. Ein Agent, der Berechtigungen erteilen kann, kann dem Berechtigungsmodell entkommen.

Bereitstellung

Separater Prozess. Führen Sie den MCP-Server neben Ihrem Django-Projekt aus:

python manage.py admin_mcp_serve

Er bedient den Pfad von MCP_URL, standardmäßig /admin/mcp, auf dem Port von MCP_URL oder 8765, wenn diese URL keinen Port nennt. Beide sind mit --host und --port überschreibbar. Nichts an Ihrer bestehenden Serving-Konfiguration ändert sich. Leiten Sie /admin/mcp über Ihren Ingress zu diesem Port und stellen Sie sicher, dass der Authorization-Header durchgereicht wird.

Gemountet (M3). Mounten Sie den Server unter /admin/mcp in der asgi.py Ihres Projekts. Eine Einschränkung: Dispatch auf den genauen Pfad. Die OAuth-Endpunkte liegen direkt unter demselben Präfix (/admin/mcp/authorize und Verwandte) und Django muss diese weiterhin bedienen, sodass ein Dispatcher, der alles unter /admin/mcp an FastMCP sendet, sie verschlucken würde. Das Rezept wird mit Meilenstein M3 geliefert.

Der Server ist zustandslos, sodass jede Instanz hinter einem Lastenausgleicher jede Anfrage bedienen kann.

Entwicklung

make install     # bootstrap uv, pin Python, install dependencies
make test        # run the permission matrix
make check       # format, lint, typecheck, and test
make migrate     # migrate the test project
make serve       # run the MCP server against the test project on :8765/admin/mcp
make help        # everything else

Lizenz

MIT