Django Admin MCP

django-admin-mcp

只需为 ModelAdmin 添加一个 mixin，MCP 客户端即可在 Django 现有权限体系内使用 CRUD、管理操作和关系遍历功能。依赖项只有 Django 和 Pydantic。

_{一个 mixin、请求在管理后台中的处理路径、一个令牌、与 Agent 的对话，然后开始使用。50 秒 · 1080p · 60 fps · 原声配乐。观看视频。}

为什么不直接让 Agent 访问数据库？

数据库连接会让 Agent 直接接触原始数据表。Django 管理后台已经定义了谁可以操作哪些内容、如何验证记录，以及哪些批量操作是允许的。这个软件包让 Agent 经过这一层，而不是绕过它：

• 权限 — 每次调用都会经过 ModelAdmin.has_*_permission()。令牌只能执行其关联用户有权执行的操作；在你授予权限之前，令牌没有任何访问权限。
• 验证 — 写入操作会运行 full_clean() 和你的 save_model() / save_related() 钩子，因此 Agent 无法保存管理表单会拒绝的记录。
• 审计历史 — 每次创建、更新、删除和操作都会以令牌对应的用户身份写入 Django 的 LogEntry。你可以查看 Agent 修改了什么，Agent 也可以读取历史记录。
• 管理操作 — “发布”、“退款”、“导出 CSV”等已注册操作都会成为工具，也支持两步确认流程。Agent 使用你设计的操作，而不是自行编写 SQL。
• 限定暴露范围 — mcp_fields / mcp_exclude_fields 可防止密码哈希和密钥出现在 Agent 的视野中；get_queryset() 仍会限制它可以查看的行。

对比

通用 Django MCP 服务或手动编写的 FastMCP 封装会要求你逐个函数自行定义工具、架构和权限检查。这个软件包会读取你已有的 ModelAdmin 类并据此生成工具，因此字段选择、查询集、验证、操作和权限都集中在一处，Agent 也会继承你对管理后台所做的每项更改。此外，它以普通 Django 应用的形式提供，无需 MCP SDK 或额外的 HTTP 技术栈。

安装

pip install django-admin-mcp

# settings.py
INSTALLED_APPS = [
    'django_admin_mcp',
    # ...
]

# urls.py
urlpatterns = [
    path('mcp/', include('django_admin_mcp.urls')),
    # ...
]

python manage.py migrate django_admin_mcp

快速开始

1. 暴露一个模型。 设置 mcp_expose = True，为其生成工具。具有该 mixin 但未设置此标志的模型，只能通过 find_models 发现。

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_article, get_article, create_article, ...
    mcp_exclude_fields = ['internal_notes']
    list_display = ['title', 'author', 'published']

@admin.register(Author)
class AuthorAdmin(MCPAdminMixin, admin.ModelAdmin):
    pass                                 # discoverable, no direct tools

2. 创建令牌，路径为 /admin/django_admin_mcp/mcptoken/。仅授予 Agent 所需的权限和组。关联用户会限制令牌的能力，并作为其变更日志中记录的身份。

3. 将 MCP 客户端指向该服务，例如在 Claude Code 的 .mcp.json 中：

{
  "mcpServers": {
    "django-admin": {
      "type": "http",
      "url": "http://localhost:8000/mcp/",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

4. 向 Agent 提问。

User: Show me the latest 10 articles
Agent: [calls list_article with limit=10]

User: Mark articles 1, 2 and 3 as published
Agent: [calls action_article with action="mark_as_published", ids=[1, 2, 3]]

User: What changed on article 42?
Agent: [calls history_article with id=42]

工具

对于每个暴露的模型（此处为 Article），服务会生成：

工具	用途
list_article, get_article	读取数据，支持分页和筛选（需要 view）
create_article, update_article, delete_article	写入单条记录（需要 add / change / delete）
bulk_article	一次创建、更新或删除多条记录
actions_article, action_article	列出并运行已注册的管理操作，包括返回文件的导出操作
describe_article	字段定义、类型和约束
related_article	跟进外键和反向关联
history_article	Django 管理后台变更历史
autocomplete_article	为外键字段搜索建议

此外，还提供用于发现所有暴露模型的 find_models、面向常见工作流的 MCP 提示词，以及 models:// 和 data:// URI 下的只读资源。此端点通过 HTTP 使用 JSON-RPC 2.0，并提供 GET /mcp/health/ 健康检查。完整参考请参阅文档。

安全概要

• 令牌格式为 mcp_<key>.<secret>；仅存储 secret 的加盐哈希。
• 每个令牌都有自己的权限和组，并与其用户的权限取交集。停用用户会使其令牌失效。
• 可配置有效期；在管理后台停用或删除令牌即可撤销。
• 日志消息中的敏感值会被隐藏，较大的操作下载文件会受 MCP_ACTION_MAX_FILE_BYTES 限制（默认值为 5 MiB）。

详情请参阅权限和令牌管理。

要求

Python 3.10 至 3.14、Django 3.2 至 6.0、Pydantic 2。已针对该范围内的每个 Django 版本进行测试。

支持此项目

如果它为你节省了时间，请在 GitHub 上点个星，帮助其他人发现此项目。欢迎提交 Issue 和 PR；请参阅贡献指南。

许可证

MIT