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.

✨ 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.
  Each action's descriptor carries a target (batch or detail),
  derived by rest-api from the callable's signature: signatures
  ending in queryset are batch (changelist shape), signatures
  ending in obj_id/pk/id are detail (single-object shape).
  Agents pass the right number of pks for the action's target.
• 🔎 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.

Why two apps?

The MCP layer is a thin wire adapter — it has no admin logic of its
own and forwards every call to
django-admin-rest-api,
which is where the actual permission checks, querysets, forms, and
serialization live. That separation lets the REST API ship and
release on its own cadence, lets the SPA frontend
(django-admin-react)
share it, and keeps the MCP package small enough to audit in an
afternoon.

If you'd rather have one URL include() instead of two:

# urls.py — one-include alternative; rest-api auto-mounted under the same prefix
urlpatterns = [
    path("admin/", admin.site.urls),
    path("",       include("django_admin_mcp_api.bundle_urls")),
]

django_admin_mcp_api.bundle_urls mounts both apps under the
consumer's chosen prefix (rest-api at <prefix>/api/v1/..., MCP at
<prefix>/mcp/). You still need both apps in INSTALLED_APPS —
that's a Django app-registration concern that can't be hidden inside
a URL conf, and manage.py check will fail with E001 if you miss
it.

📡 The 18 tools

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

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.3" },
    "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.

🤖 How an agent uses admin.action

Each registered action on a ModelAdmin has one of two shapes — and
the agent picks the call form by reading the descriptor:

1. Discover. Call admin.registry or admin.list. Each action
   in the response carries a target field:

   {
     "name": "deactivate",
     "label": "Deactivate selected users",
     "target": "batch"           // or "detail"
   }
   

2. Branch on target.
   • target = "batch" → the action's third parameter is a
     queryset. Call admin.action with one or more pks.
   • target = "detail" → the action's third parameter is a single
     object id. Call admin.action with exactly one pk.

rest-api inspects the signature at registry time, so you don't need
to declare the shape — the same ModelAdmin.actions = [...] you
already use works. Passing the wrong number of pks for the target
returns rest-api's 400 with an explicit "expected 1, got N" message.

// batch action
{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "admin.action",
    "arguments": {
      "app_label":   "auth",
      "model_name":  "user",
      "action_name": "deactivate",
      "pks":         ["7", "12", "33"]
    }
  }
}

// detail action — exactly one pk
{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "admin.action",
    "arguments": {
      "app_label":   "auth",
      "model_name":  "user",
      "action_name": "send_password_reset",
      "pks":         ["7"]
    }
  }
}

See docs/tools-reference.md for the full
schema, and docs/api-contract.md for the
wire-level error codes.

⚙️ 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. Override
    # for custom AdminSite subclasses — see "Custom AdminSite" below.
    "ADMIN_SITE":        "django.contrib.admin.site",

    # Maximum POST body size for /mcp/, in bytes. Default 256 KiB —
    # well above any realistic JSON-RPC envelope and well below
    # Django's project-wide DATA_UPLOAD_MAX_MEMORY_SIZE (2.5 MiB)
    # which targets form uploads.
    "MAX_REQUEST_BYTES": 256 * 1024,

    # Tools to suppress from the catalogue and refuse in tools/call.
    # Read-only deployments typically set
    # ("admin.destroy", "admin.bulk_update", "admin.set_password").
    "DISABLED_TOOLS":    (),

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

Custom AdminSite

If your project subclasses Django's AdminSite (multi-tenant flavours,
a staff-only admin alongside a partner admin, etc.), point the package
at the right instance via the ADMIN_SITE setting:

# myproject/admin_sites.py
from django.contrib.admin import AdminSite

class StaffAdminSite(AdminSite):
    site_header = "Staff console"

staff_admin = StaffAdminSite(name="staff_admin")

# settings.py
DJANGO_ADMIN_MCP_API = {
    "ADMIN_SITE": "myproject.admin_sites.staff_admin",
}

A single /mcp/ mount exposes exactly one AdminSite. If you need
two MCP surfaces (one per AdminSite), mount the package twice — once
under /staff-mcp/, once under /partner-mcp/ — each with the right
ADMIN_SITE pointer.

manage.py check integration

manage.py check validates the install at boot. It catches:

• E001 — django_admin_rest_api missing from INSTALLED_APPS.
• E002 — ADMIN_SITE dotted path doesn't resolve.
• W001 — DISABLED_TOOLS lists names that don't match any tool (typo guard).

🔒 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

120 tests, 95% 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.

🔌 Use it from your agent

Drop-in config snippets for the major MCP clients live under
examples/clients/:

• claude-desktop.json — Anthropic Claude Desktop
• cursor.json — Cursor
• vscode-mcp.json — VS Code MCP extensions

Each is a working template — replace the URL + session/CSRF
placeholders with your deployment's values and the client can drive
the admin.

Headless / scripted clients

For Python scripts, CI jobs, and services that can't drive a
browser, examples/headless-client/
ships a programmatic-login recipe: bootstrap.py logs in once and
writes a cookies file; call.py re-uses it for any MCP method call
(stdlib-only). The same Django session-auth flow your HTML admin
already uses — just scripted.

🤝 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 ruff (check + format + import sorting),
mypy --strict, bandit, pip-audit, gitleaks. Every change must pass
all of them before merge.

📜 License

MIT. See LICENSE.