Django MCP Server

Django MCP 服务

Django MCP Server 是面向 Django 的 Model Context Protocol（MCP） 扩展实现。此模块让 MCP 客户端和 AI Agent 能够无缝地与任何 Django 应用交互。

🚀 采用 Django 风格的声明式工具，让 AI Agent 和 MCP 客户端能够与 Django 交互。
🚀 只需 2 行代码，即可安全地向 AI Agent 和 MCP 工具开放 Django 模型供其查询。
🚀 通过一个注解将 Django Rest Framework API 转换为 MCP 工具。
✅ 无需更改基础设施，即可同时运行于 WSGI 和 ASGI。
✅ 已通过与 Claude AI 的远程集成验证。
🤖 任何支持 MCP 的 MCP 客户端或 AI Agent（Google Agent Developement Kit、Claude AI、Claude Desktop 等）都能与您的应用交互。

衷心感谢🙏所有贡献者社区

由 Smart GTS software engineering 悉心维护✨。

基于 MIT License 授权。

---

功能

• 将 Django 模型和逻辑开放为 MCP 工具。
• 在 Django 应用中提供 MCP 端点。
• 轻松集成 AI Agent、MCP 客户端或 Google ADK 等工具。

---

快速开始

1️⃣ 安装

pip install django-mcp-server

或直接从 GitHub 安装：

pip install git+https://github.com/omarbenhamid/django-mcp-server.git

---

2️⃣ 配置 Django

✅ 将 mcp_server 添加到 INSTALLED_APPS：

INSTALLED_APPS = [
    # your apps...
    'mcp_server',
]

✅ 将 MCP 端点添加到 urls.py：

from django.urls import path, include

urlpatterns = [
    # your urls...
    path("", include('mcp_server.urls')),
]

默认情况下，MCP 端点位于 /mcp。

---

3️⃣ 定义 MCP 工具

在 mcp.py 中创建 ModelQueryToolset 的子类，以开放对某个模型的访问：

from mcp_server import ModelQueryToolset
from .models import *


class BirdQueryTool(ModelQueryToolset):
    model = Bird

    def get_queryset(self):
        """self.request can be used to filter the queryset"""
        return super().get_queryset().filter(location__isnull=False)

class LocationTool(ModelQueryToolset):
    model = Location

class CityTool(ModelQueryToolset):
    model = City

或者创建 MCPToolset 的子类以发布通用方法（私有的 _ 方法不会被发布）

示例：

from mcp_server import MCPToolset
from django.core.mail import send_mail

class MyAITools(MCPToolset):
    def add(self, a: int, b: int) -> list[dict]:
        """A service to add two numbers together"""
        return a+b

    def send_email(self, to_email: str, subject: str, body: str):
        """ A tool to send emails"""

        send_mail(
             subject=subject,
             message=body,
             from_email='[email protected]',
             recipient_list=[to_email],
             fail_silently=False,
         )

---

使用 MCP Inspect 验证

使用管理命令 mcp_inspect，确保工具声明正确：

python manage.py mcp_inspect

将 MCP 用于任何 MCP 客户端

现在，MCP 工具已发布在 Django 应用的 /mcp 端点上。

重要：在生产环境中，如果数据非公开，请考虑通过以下配置启用授权： DJANGO_MCP_AUTHENTICATION_CLASSES

使用 MCP Python SDK 测试

您可以使用 Python MCP SDK 进行测试：

from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession


async def main():
    # Connect to a streamable HTTP server
    async with streamablehttp_client("http://localhost:8000/mcp") as (
        read_stream,
        write_stream,
        _,
    ):
        # Create a session using the client streams
        async with ClientSession(read_stream, write_stream) as session:
            # Initialize the connection
            await session.initialize()
            # Call a tool
            tool_result = await session.call_tool("get_alerts", {"state": "NY"})
            print(tool_result)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

将 http://localhost:8000/mcp 替换为实际的 Django 主机，然后运行此脚本。

在 Claude AI 中使用

截至 2025 年 6 月，Claude AI 现已通过 streamable HTTP 协议支持 MCP，前提条件如下： *

• 配置 OAuth2，例如：
  • 安装 Django Oauth Toolkit)
  • 在 settings.py 的 DJANGO_MCP_AUTHENTICATION_CLASSES 中加入 'oauth2_provider.contrib.rest_framework.OAuth2Authentication'
• Claude AI 需要动态客户端注册。截至目前，django oauth toolkit 尚不支持，但您可以使用此 Django Oauth Toolkit DCR Add-On
• 除非您正确实现 OAuth server Metadata RFC，否则需要将 OAuth2 URL（/register、/token 和 /authorize）保留在默认位置。

在 Claude Desktop 中测试

你可以在 Claude Desktop 中测试 MCP 服务。目前，Claude Desktop 仅支持本地 MCP 服务。因此，你需要在同一台机器上安装应用，通常是在开发环境中。

为此，你需要：

1. 从 claude.ai 安装 Claude Desktop
2. 打开 File > Settings > Developer，然后点击 Edit Config
3. 打开 claude_desktop_config.json 并配置你的 MCP 服务：

   {
    "mcpServers": {
        "test_django_mcp": {
            "command": "/path/to/interpreter/python",
            "args": [
                "/path/to/your/project/manage.py",
                "stdio_server"
            ]
        }
    }
   

注意 /path/to/interpreter/ 应指向你使用的 Python 解释器（例如，可以是虚拟环境中的解释器），而 /path/to/your/project/ 是你的 Django 项目路径。

高级主题

将 Django Rest Framework API 发布为 MCP 工具

你可以将 drf_publish_create_mcp_tool / drf_publish_update_mcp_tool / drf_publish_delete_mcp_tool / drf_publish_list_mcp_tool 用作注解或方法调用，以便将基于 DRF CreateModelMixin / UpdateModelMixin / DestroyModelMixin / ListModelMixin 的视图无缝注册为 MCP 工具。Django MCP Server 会生成相应的架构， 以便 MCP 客户端使用这些工具。

注意 在某些较旧的 DRF 版本中，默认不支持架构生成，因此你需要向注册注解提供

from mcp_server import drf_publish_create_mcp_tool

@drf_publish_create_mcp_tool
class MyModelView(CreateAPIView):
    """
    A view to create MyModel instances
    """
    serializer_class=MySerializer

请注意，视图的文档字符串会用作模型的指令。 你可以像这样进一步调整：

@drf_publish_create_mcp_tool(instructions="Use this view to create instances of MyModel")
class MyModelView(CreateAPIView):
    """
    A view to create MyModel instances
    """
    serializer_class=MySerializer

最后，你可以手动在 mcp.py 中注册，例如：

drf_publish_update_mcp_tool(MyDRFAPIView, instructions="Use this tool to update my model, but use it with care")

重要

请注意，内置身份验证类默认处于禁用状态，filter_backends、permission_classes 和 pagination_class 也同样如此，因为这里使用的是 MCP 身份验证。

由于 pagination_class 也处于禁用状态，如果你使用现有的分页 DRF 视图，就需要对此进行处理（self.paginator 将为 None）。

Django Rest Framework 序列化器集成

你可以使用 drf_serialize_output(...) 为工具添加注解，以使用 django rest framework 序列化其输出，例如：

from mcp_server import drf_serialize_output
from .serializers import FooBarSerializer
from .models import FooBar

class MyTools(MCPToolset):
   @drf_serialize_output(FooBarSerializer)
   def get_foo_bar():
       return FooBar.objects.first()

使用低级 MCP 服务注解

你可以导入 DjangoMCP 服务实例，并使用 FastMCP 注解声明 MCP 工具和资源：

from mcp_server import mcp_server as mcp
from .models import Bird


@mcp.tool()
async def get_species_count(name: str) -> int:
    '''Find the ID of a bird species by name (partial match). Returns the count.'''
    ret = await Bird.objects.filter(species__icontains=name).afirst()
    if ret is None:
        ret = await Bird.objects.acreate(species=name)
    return ret.count

@mcp.tool()
async def increment_species(name: str, amount: int = 1) -> int:
    '''
    Increment the count of a bird species by a specified amount.
    Returns the new count.
    '''
    ret = await Bird.objects.filter(species__icontains=name).afirst()
    if ret is None:
        ret = await Bird.objects.acreate(species=name)
    ret.count += amount
    await ret.asave()
    return ret.count

⚠️ 重要：

1. 定义异步工具时，始终使用 Django 的异步 ORM API。
2. 注意不要返回 QuerySet，因为它会被异步求值，从而导致错误。

自定义默认 MCP 服务设置

你可以在 settings.py 中初始化 DJANGO_MCP_GLOBAL_SERVER_CONFIG 参数。这些参数将 在初始化期间传递给 MCPServer 服务。

DJANGO_MCP_GLOBAL_SERVER_CONFIG = {
    "name":"mymcp",
    "instructions": "Some instructions to use this server",
    "stateless": False
}

会话管理

默认情况下，服务是有状态的，状态由 Django 会话 request.session 对象管理，因此必须正确配置会话后端。对于基于类的工具集， 可以通过 self.request 获取请求对象。

注意 无需配置会话中间件，因为 MCP 会话由 MCP 独立管理，且不使用 Cookie。 . 你可以通过定义 DJANGO_MCP_GLOBAL_SERVER_CONFIG 使服务变为无状态。

重要 状态由 django 会话管理。例如，如果你使用低级 @mcp_server.tool() 注解， 由于 Django 在 WSGI 部署中的架构，同一基础 Python API 的多次调用可能由不同线程处理，因此无法保留服务实例的状态！

授权

MCP 端点支持 Django Rest Framework 授权类 你可以在 settings.py 中使用 DJANGO_MCP_AUTHENTICATION_CLASSES 设置它们，例如：

DJANGO_MCP_AUTHENTICATION_CLASSES=["rest_framework.authentication.TokenAuthentication"]

重要：现在，MCP Specification version 2025-03-26 建议使用 OAuth2 工作流，因此你应该集成 django-oauth-toolkit with djangorestframework integration 设置，并在 DJANGO_MCP_AUTHENTICATION_CLASSES 中使用 'oauth2_provider.contrib.rest_framework.OAuth2Authentication'。请参阅 django-oauth-toolkit 的官方文档

视图的高级／自定义设置

你可以在 urls.py 中挂载 MCPServerStreamableHttpView.as_view() 视图，并使用任何额外参数对其进行自定义。

ModelQueryToolset 的自定义输出格式（渲染器）

你可以定义任意 DRF 渲染器来生成输出。为此， 必须在 settings 中声明：

DJANGO_MCP_OUTPUT_RENDERER_CLASSES = [
    "rest_framework.renderers.JSONRenderer",
    "rest_framework_csv.renderers.CSVRenderer"
]

然后，你可以在 ModelQueryToolset 声明中添加

    ...
    output_format="csv"

此外，你还可以指示工具将结果作为 [MCP Embedded Resource] 附加，而不是直接返回：

    ...
    output_as_resource=True

注意：某些渲染器（如 drf-excel）的设计不允许在 DRF View 之外使用，因此在这里无法运行……

次要 MCP 端点

在 mcp.py 中

from mcp_server.djangomcp import DjangoMCP

second_mcp = DjangoMCP(name="altserver")

@second_mcp.tool()
async def my_tool():
    ...

在 urls.py 中

...
from yourapp.mcp import second_mcp
...
path("altmcp", MCPServerStreamableHttpView.as_view(mcp_server=second_mcp))
...

重要：这样做时，DJANGO_MCP_AUTHENTICATION_CLASSES 设置会被忽略，你的视图将不安全。你应该为视图设置 DRF 身份验证，例如：

...
MCPServerStreamableHttpView.as_view(permission_classes=[IsAuthenticated], authentication_classes=[TokenAuthentication])
...

测试

服务端

你可以设置自己的应用，也可以使用 mcpexample django app 应用。

客户端

默认情况下，你的 MCP 服务将在 <your_django_server>/mcp 提供 无状态的可流式传输 HTTP 传输 端点（例如 http://localhost:8000/mcp）（*末尾不要加 /！）。

有很多种测试方式：

1. 使用测试 MCP 客户端脚本：test/test_mcp_client.py
2. 使用 MCP Inspector 工具 进行测试
3. 或使用任何兼容的 MCP 客户端，例如 Google Agent Development Kit。

---

与 Agent 框架和 MCP 客户端集成

Google Agent Development Kit 示例

注意：截至目前，Google 官方 ADK 不支持 StreamableHTTP Transport， 但你可以使用这个分支。

然后，你可以使用 test/test_agent 中的测试 Agent，方法是在 test 文件夹中 启动 adk web。请先确保：

1. 安装支持 streamablehttp 的 ADK：pip install git+https://github.com/omarbenhamid/google-adk-python.git
2. 启动一个带有 MCP 端点的 Django 应用：在 examples/mcpexample 文件夹中运行 python manage.py runserver。
3. 如果使用 TokenAuthorization，请创建访问令牌，例如在应用的 Django Admin 中创建。
4. 在 test/test_agent/agent.py 中设置正确的端点位置和身份验证标头
5. 进入 test 文件夹。
6. 运行 adk web
7. 在 Shell 中，你可以使用如下提示词：“我看到了 woody woodpecker，把它添加到我的库存中。”

其他客户端

你可以轻松地将 MCP 服务端点接入任何支持 MCP 可流式传输 HTTP 服务的 Agent 框架。 请参阅这份客户端列表

---

设置

• DJANGO_MCP_GLOBAL_SERVER_CONFIG 全局 MCP 服务的配置字典，默认为空。可包含以下参数：

  • name：服务名称
  • instructions：全局指令
  • stateless：设为 'True' 时，服务将不会管理会话

• DJANGO_MCP_AUTHENTICATION_CLASSES（默认不进行身份验证）一个 Django Rest Framework 身份验证类的引用列表，用于在主 MCP 视图中强制执行身份验证。

• DJANGO_MCP_GET_SERVER_INSTRUCTIONS_TOOL（默认=True）如果为 true，将提供一个用于获取全局指令的工具，并指示工具让 Agent 使用它，因为 Agent 的系统提示词中并不总是包含 MCP 服务的全局指令。

• DJANGO_MCP_ENDPOINT（默认="mcp"）一个字符串，表示服务使用的 URL 端点。例如，如果希望末尾带有斜杠，请将其设为 "mcp/"

路线图

• ✅ 无状态流式 HTTP 传输（已实现）
• 🔜 用于开发配置（例如 Claude Desktop）的 STDIO 传输集成
• 🔜 ****
• 🔜 使用 Django 会话的有状态流式 HTTP 传输
• 🔜 SSE 端点集成（需要 ASGI）
• 🔜 改进错误管理和日志记录

---

问题

如果遇到错误或有功能请求，请在 GitHub Issues 上提交问题。

---

许可证

MIT License。