django-admin-mcp-api 1.0.1

MCP (Model Context Protocol) adapter for django-admin-rest-api. A wire-protocol-only layer that lets agents reach the existing REST API — no new functionality, permissions, or validation.

django-admin-mcp-api

An MCP server for the Django admin — same permissions, same ModelAdmin, no new features.

django-admin-mcp-api lets AI agents — Claude, Cursor, anything that speaks the Model Context Protocol — drive your Django admin. Every ModelAdmin you've already registered on django.contrib.admin.site becomes an MCP tool, with the same permissions, the same form validation, and the same session auth as the HTML admin.

It is the MCP face on top of django-admin-rest-api. No parallel permission system. No parallel form layer. No features the Django admin doesn't already have.

Project	Role	PyPI
🟦 django-admin-react	React single-page admin frontend	django-admin-react
🟩 django-admin-rest-api	JSON REST API over ModelAdmin	django-admin-rest-api
🟪 django-admin-mcp-api (this repo)	MCP server exposing the same API to LLMs	django-admin-mcp-api

---

✨ The one design principle

This package adds no new behavior. It is an MCP wire adapter.

Every one of these is owned by your existing Django setup — not by this library:

• 🔐 Authentication — Django's session + login. The MCP endpoint enforces the same is_active + is_staff + AdminSite.has_permission gate the HTML admin uses. No tokens, no custom backends, no JWTs.
• 🛡️ Authorization — every tool delegates to the matching ModelAdmin.has_view_permission / has_add_permission / has_change_permission / has_delete_permission via django-admin-rest-api. If your admin says no, the tool returns the upstream 403.
• 📋 Field validation — admin.create / admin.update route the payload through the same ModelForm Django would render in the HTML admin, plus a JSON Schema check on the wire so malformed calls fail fast with a json-pointer path of the offending field.
• ⚙️ Actions — admin.action runs the same action callables registered on ModelAdmin.actions. Your code runs unmodified.
• 🔎 Search & filters — admin.list uses ModelAdmin.get_search_results and list_filter. No parallel implementation.
• 📜 Audit log — writes go through Django's LogEntry, surfaced by admin.history and admin.recent_actions.
• 🌐 CSRF & sessions — Django's middleware. Nothing is @csrf_exempt.

If a behavior isn't in the HTML admin, it isn't here. If it is in the HTML admin, this library exposes it over MCP.

---

🚀 Plug-and-play install

pip install django-admin-mcp-api

Two changes to your project:

# settings.py
INSTALLED_APPS = [
    # ... your existing apps ...
    "django.contrib.admin",
    "django_admin_rest_api",         # ← the REST surface (mandatory)
    "django_admin_mcp_api",          # ← the MCP adapter
]

# urls.py
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("admin/",  admin.site.urls),
    path("",        include("django_admin_rest_api.urls")),    # REST
    path("mcp/",    include("django_admin_mcp_api.urls")),     # MCP
]

That's it. Your admin now answers JSON-RPC at POST /mcp/, with the same session cookie and CSRF token your HTML admin already uses.

---

📡 The 16 tools

Each MCP tool is a 1:1 mirror of a django-admin-rest-api endpoint — that's the whole design.

MCP tool	What it does	rest-api endpoint
admin.registry	List every model the user can see	GET /api/v1/registry/
admin.schema	Full admin metadata schema	GET /api/v1/schema/
admin.recent_actions	The user's own LogEntry feed	GET /api/v1/recent-actions/
admin.list	A page of list-view results	GET /api/v1/<app>/<model>/
admin.retrieve	A single object's detail view	GET /api/v1/<app>/<model>/<pk>/
admin.add_form	Create-page field descriptors	GET /api/v1/<app>/<model>/add/
admin.create	Create one object	POST /api/v1/<app>/<model>/
admin.update	Partial-update one object	PATCH /api/v1/<app>/<model>/<pk>/
admin.destroy	Delete one object	DELETE /api/v1/<app>/<model>/<pk>/
admin.bulk_update	Apply the same patch to many objects	PATCH /api/v1/<app>/<model>/bulk/
admin.autocomplete	Autocomplete a related model	GET /api/v1/<app>/<model>/autocomplete/
admin.action	Run a ModelAdmin.actions action	POST /api/v1/<app>/<model>/actions/<name>/
admin.history	One object's LogEntry timeline	GET /api/v1/<app>/<model>/<pk>/history/
admin.delete_preview	Cascade preview before a destroy	GET /api/v1/<app>/<model>/<pk>/delete-preview/
admin.set_password	Set/change a user-like password	POST /api/v1/<app>/<model>/<pk>/password/
admin.panel	A custom panel registered on the ModelAdmin	GET /api/v1/<app>/<model>/<pk>/panel/<name>/

Two endpoints expose them — both gated by the same auth your admin already has:

• POST /mcp/ — the MCP JSON-RPC 2.0 entry point. Speaks initialize, tools/list, tools/call. Full wire spec in docs/api-contract.md.
• GET /mcp/manifest/ — a read-only catalogue (server info + every tool's name, description, JSON Schema) for humans and dashboards.

---

📸 See it run

Captured against the examples/quickstart/ demo — fresh pip install, runserver, python smoke.py. No mocks.

// POST /mcp/  method=initialize
{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo":      { "name": "django-admin", "version": "1.0.0" },
    "capabilities":    { "tools": { "listChanged": false } }
  }
}

// POST /mcp/  method=tools/call  name=admin.registry
{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "content": [{ "type": "json", "json": {
      "user":  { "id": 1, "username": "admin", "is_staff": true },
      "apps":  [
        { "app_label": "auth",
          "models": [
            { "model_name": "group",
              "permissions": { "view": true, "add": true, "change": true, "delete": true } },
            { "model_name": "user",
              "permissions": { "view": true, "add": true, "change": true, "delete": true } }
          ] }
      ]
    } }],
    "isError": false,
    "status":  200
  }
}

The permissions block above comes straight from ModelAdmin.has_*_permission — the MCP layer doesn't decide a thing about authorization. That's the prime directive.

---

⚙️ Configuration

All settings live under a single optional dict — defaults are sane, so most projects need no entry at all.

# settings.py (all keys optional)
DJANGO_ADMIN_MCP_API = {
    # MCP protocol version advertised in the `initialize` result.
    "PROTOCOL_VERSION":  "2024-11-05",

    # The `serverInfo.name` field. Useful per-environment labelling.
    "SERVER_NAME":       "django-admin",

    # The `serverInfo.version`. None → falls back to the package version.
    "SERVER_VERSION":    None,

    # Dotted path to the AdminSite the package introspects.
    "ADMIN_SITE":        "django.contrib.admin.site",

    # Dotted path to a zero-arg callable returning a Dispatcher.
    # None uses the built-in RestApiDispatcher.
    "DISPATCHER_FACTORY": None,
}

A copy-paste-ready block lives at the bottom of examples/quickstart/myproject/settings.py.

---

🔒 Security

• The MCP endpoint is not a parallel auth surface. It refuses any caller the HTML admin would refuse, with the same gate.
• Anonymous → 401. Authenticated but non-staff → 403. CSRF missing on POST → Django's middleware 403.
• Every tools/call is validated against the tool's JSON Schema before it reaches the database. Schema violations return INVALID_PARAMS with the json-pointer path of the failing field.
• The dispatcher carries the caller's session / user / cookies / CSRF state to django-admin-rest-api untouched. Per-tool permission is enforced inside rest-api by the relevant ModelAdmin.has_*_permission.
• CSRF is enforced everywhere. No view in this package is @csrf_exempt — a pre-commit hook and a test assert this.
• No token-shaped string is permitted in the repo (gitleaks + a pygrep hook + tests/test_security.py).

Threat model: docs/threat-model.md. Report a vulnerability privately here.

---

🧪 Local development

git clone https://github.com/MartinCastroAlvarez/django-admin-mcp-api
cd django-admin-mcp-api
poetry install
poetry run pytest
poetry run bash scripts/lint.sh
poetry run bash scripts/audit-deps.sh

77 tests, 91% line coverage, including a real end-to-end run through django-admin-rest-api. CI runs the same suite across Python 3.10–3.13 × Django 5.0/5.1/5.2/6.0 on every PR.

---

🤝 Contributing

Issues, PRs, and the roadmap are on GitHub:

• 📋 Issues
• 🗺️ Project board
• 📖 CONTRIBUTING.md — house rules
• 🤖 CLAUDE.md — agent contract

The lint + security gate is the same set the upstream django-admin-rest-api and django-admin-react repos use: ruff, black, isort, flake8, pylint, mypy, bandit, pip-audit, gitleaks. Every change must pass all of them before merge.

---

📜 License

MIT. See LICENSE.