django-admin-mcp
Expose Django admin models to MCP (Model Context Protocol) clients via HTTP. Add a mixin to your ModelAdmin classes and get instant access to CRUD operations, admin actions, model history, and more.
Features
- Only two dependencies — Django and Pydantic, nothing else. No MCP SDK, no extra HTTP stack, no supply-chain sprawl
- Token authentication — secure Bearer token auth with configurable expiry
- Django admin permissions — respects existing view/add/change/delete permissions
- Field filtering — control which fields are exposed via
mcp_fields and mcp_exclude_fields
- Full CRUD — list, get, create, update, delete operations
- Admin actions — execute registered Django admin actions, including two-step confirmation flows
- Bulk operations — create, update, or delete multiple records at once
- Model introspection — describe model fields and relationships
- Related objects — traverse foreign keys and reverse relations
- Change history — access Django admin's history log
- Autocomplete — search suggestions for foreign key fields
- MCP Prompts & Resources — workflow guides plus read-only data access via
models:// and data:// URIs
Installation
pip install django-admin-mcp
Add to your Django project:
INSTALLED_APPS = [
'django_admin_mcp',
]
from django.urls import path, include
urlpatterns = [
path('mcp/', include('django_admin_mcp.urls')),
]
Run migrations to create the token model:
python manage.py migrate django_admin_mcp
Quick Start
1. Expose Your Models
Add the mixin to any ModelAdmin. Set mcp_expose = True to expose direct tools:
from django.contrib import admin
from django_admin_mcp import MCPAdminMixin
from .models import Article, Author
@admin.register(Article)
class ArticleAdmin(MCPAdminMixin, admin.ModelAdmin):
mcp_expose = True
list_display = ['title', 'author', 'published']
@admin.register(Author)
class AuthorAdmin(MCPAdminMixin, admin.ModelAdmin):
pass
Protecting Sensitive Fields
Use mcp_exclude_fields to prevent sensitive data exposure:
@admin.register(User)
class UserAdmin(MCPAdminMixin, admin.ModelAdmin):
mcp_expose = True
mcp_exclude_fields = ['password', 'security_token']
2. Create an API Token
Go to Django admin at /admin/django_admin_mcp/mcptoken/ and create a token. Grant the token exactly the permissions the agent needs via its Permissions and Groups fields — tokens start with no access. The linked user caps the token (it can never exceed that user's permissions) and is the audit identity actions are logged under.
Add to your MCP client settings (e.g. a project .mcp.json for Claude Code):
{
"mcpServers": {
"django-admin": {
"type": "http",
"url": "http://localhost:8000/mcp/",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
4. Use with Your Agent
Once configured, the agent can use the tools directly:
User: What models are available in Django admin?
Agent: [calls find_models tool]
User: Show me the latest 10 articles
Agent: [calls list_article with limit=10]
User: Get article #42 and update its title to "New Title"
Agent: [calls get_article with id=42, then update_article]
For each exposed model (e.g., Article), the following tools are generated:
CRUD Operations
| Tool | Description |
|---|
list_article | List all articles with pagination (limit, offset) and filtering |
get_article | Get a single article by id |
create_article | Create a new article with field values |
update_article | Update an existing article by id |
delete_article | Delete an article by id |
Model Introspection
| Tool | Description |
|---|
find_models | Discover all exposed models and their available tools |
describe_article | Get field definitions, types, and constraints |
Admin Actions
| Tool | Description |
|---|
actions_article | List available admin actions for the model |
action_article | Execute an admin action on selected records |
bulk_article | Bulk create, update, or delete multiple records |
Relationships
| Tool | Description |
|---|
related_article | Get related objects via foreign keys |
history_article | View Django admin change history |
autocomplete_article | Search suggestions for autocomplete fields |
HTTP Protocol Reference
For custom integrations, the MCP endpoint accepts JSON-RPC 2.0 POST requests:
curl -X POST http://localhost:8000/mcp/ \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
curl -X POST http://localhost:8000/mcp/ \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "list_article", "arguments": {"limit": 10}}}'
Supported methods: initialize, notifications/initialized, tools/list, tools/call, prompts/list, prompts/get, resources/list, resources/templates/list, and resources/read. A GET /mcp/health/ endpoint is available for health checks.
Example Conversations
CRUD Operations
User: Create a new article titled "Getting Started with Django"
Agent: I'll create that article for you.
[calls create_article with title="Getting Started with Django"]
Created article #15: "Getting Started with Django"
User: Update article 15 to add content
Agent: [calls update_article with id=15, content="..."]
Updated article #15 successfully.
User: Delete article 15
Agent: [calls delete_article with id=15]
Deleted article #15.
Admin Actions
User: Mark articles 1, 2, and 3 as published
Agent: [calls action_article with action="mark_as_published", ids=[1,2,3]]
Marked 3 articles as published.
When an admin action returns a Django HttpResponse / StreamingHttpResponse (typical for CSV/TSV/PDF downloads), action_<model> serializes the body instead of str(response):
{
"success": true,
"action": "export_csv",
"affected_count": 2,
"result": {
"type": "file",
"encoding": "utf-8",
"content_type": "text/csv; charset=utf-8",
"filename": "export.csv",
"content_disposition": "attachment; filename=\"export.csv\"",
"size": 10,
"status_code": 200,
"content": "a,b\r\n1,2\r\n"
}
}
Text-ish content types (text/*, application/json, …) decode using the Content-Type charset (or response.charset, default UTF-8) and return "encoding": "utf-8" with Unicode text in content. If that decode fails (unknown charset or invalid bytes), the payload falls back to "encoding": "base64" like binary downloads. Binary payloads use "encoding": "base64" with ASCII base64 in content.
Large downloads are rejected once the body exceeds MCP_ACTION_MAX_FILE_BYTES (default 5 MiB) to protect MCP transports.
Bulk Operations
User: Set status to "archived" for articles 10-15
Agent: [calls bulk_article with operation="update", ids=[10,11,12,13,14,15], data={"status": "archived"}]
Updated 6 articles.
User: Delete all draft articles from last month
Agent: [calls list_article to find drafts, then bulk_article with operation="delete"]
Deleted 12 draft articles.
Exploring Relationships
User: Show me all comments on article 42
Agent: [calls related_article with id=42, relation="comments"]
Found 8 comments on article #42...
User: What changes were made to article 42?
Agent: [calls history_article with id=42]
Change history for article #42:
- 2024-01-15: Changed title (admin)
- 2024-01-10: Created (admin)
Model Discovery
User: What can I manage through MCP?
Agent: [calls find_models]
Available models:
- article (5 tools: list, get, create, update, delete)
- author (5 tools: list, get, create, update, delete)
- category (5 tools: list, get, create, update, delete)
User: What fields does article have?
Agent: [calls describe_article]
Article fields:
- id (AutoField, read-only)
- title (CharField, max_length=200, required)
- content (TextField, optional)
- author (ForeignKey to Author, required)
- published (BooleanField, default=False)
- created_at (DateTimeField, auto)
Security
Two-Level Exposure
Models with MCPAdminMixin are automatically discoverable via the find_models tool, allowing the agent to see what's available. To expose full CRUD tools directly, set mcp_expose = True:
class AuthorAdmin(MCPAdminMixin, admin.ModelAdmin):
pass
class ArticleAdmin(MCPAdminMixin, admin.ModelAdmin):
mcp_expose = True
Token Authentication
- Tokens are created in Django admin (format:
mcp_<key>.<secret>; only a salted hash of the secret is stored)
- Each token carries its own permissions and groups, capped by the linked Django user's permissions: a token can narrow its user's access but never exceed it
- Tokens start with no permissions (principle of least privilege); even a superuser-bound token has no access until granted
- The linked user is also the audit identity actions are logged under; deactivating the user disables all its tokens' access
- Token expiry is configurable (blank in the admin form = never expires; programmatic creation defaults to 90 days)
- Revoke tokens by deactivating or deleting them in admin
Permission Checking
All operations go through ModelAdmin.has_*_permission(), answered from the token's effective permissions (its grants intersected with the linked user's permissions):
| Operation | Required Permission |
|---|
list_* / get_* | view |
create_* | add |
update_* | change |
delete_* | delete |
If the token lacks the permission, the operation returns an error.
Requirements
| Dependency | Version |
|---|
| Python | >= 3.10 |
| Django | >= 3.2 |
| Pydantic | >= 2.0 |
Supported Django Versions
Django 3.2 · 4.0 · 4.1 · 4.2 · 5.0
License
MIT