Django MCP Server

Django MCP Server 是 Django 的 模型上下文协议（MCP） 扩展实现。此模块允许 MCP 客户端 和 AI 代理 无缝地与任何 Django 应用程序交互。

✅ 在现有的 WSGI 应用程序中运行。
🚀 实现了 流式 HTTP 传输（无状态）。
🛣️ 有状态传输 和 服务器发送事件（SSE）响应 已列入路线图（需要 ASGI）。

根据 MIT 许可证 授权。

---

功能

• 将 Django 模型和逻辑暴露为 MCP 工具。
• 在 Django 应用程序内提供 MCP 端点。
• 轻松集成 AI 代理、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 = [
    # 您的应用程序...
    'mcp_server',
]

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

from django.urls import path, include

urlpatterns = [
    # 您的 URL...
    path("", include('mcp_server.urls')),
]

默认情况下，MCP 端点将在 /mcp 可用。

---

3️⃣ 定义 MCP 工具

在您的 Django 应用程序中创建一个名为 mcp.py 的文件，并创建 MCPToolset 的子类：每个不以 _ 开头的方法都将作为工具发布。

示例：

from mcp_server import MCPToolset
from .models import Bird

class SpeciesCount(MCPToolset):
    mcp_server = None # None 表示使用全局 mcp_server，也可以指定本地的一个，如果这样，您需要在 urls.py 中注册它，请参阅 README

    def _search_birds(self, search_string: str | None = None) -> Bird:
        """获取鸟类的查询集，
        以 _ 开头的方法不会被注册为工具"""
        return Bird.objects.all() if search_string is None else Bird.objects.filter(species__icontains=search_string)

    def list_species(self, search_string: str | None = None) -> list[dict]:
        """列出所有物种及其数量，返回找到的每个物种的名称和数量"""
        return list(self._search_birds(search_string).values('species', 'count'))

    def increment_species(self, name: str, amount: int = 1) -> int:
        """
        增加特定鸟类的数量并返回新的数量。
        第一个参数是物种名称，第二个参数是增加的数量，默认为 1。
        """
        ret = self._search_birds(name).first()
        if ret is None:
            ret = Bird.objects.create(species=name)

        ret.count += amount
        ret.save()

        return ret.count

---

高级主题

使用低级别的 MCP 服务器注解

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

from mcp_server import mcp_server as mcp
from .models import Bird

print("定义工具")

@mcp.tool()
async def get_species_count(name: str) -> int:
    '''通过名称（部分匹配）查找鸟类物种的数量。'''
    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:
    '''
    增加特定鸟类的数量。
    返回新的数量。
    '''
    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

⚠️ 重要：在这种情况下始终使用 Django 的异步 ORM API。

自定义默认 MCP 服务器设置

在 settings.py 中，您可以初始化 DJANGO_MCP_GLOBAL_SERVER_CONFIG 参数。这些参数将在初始化时传递给 MCPServer 服务器：

DJANGO_MCP_GLOBAL_SERVER_CONFIG = {
    "name":"mymcp",
    "instructions": "使用此服务器的一些说明"
}

授权

使用 DRF 注解，您可以在 urls.py 中启用授权：

path("mcp", api_view(['GET','POST'])(permission_classes([IsAuthenticated])(MCPServerStreamableHttpView.as_view())))

为了符合 MCP 规范，您应该支持 OAuth2，因此可以集成例如 django-oauth-toolkit。

次要 MCP 端点

在 mcp.py 中：

second_mcp = DjangoMCP(name="altserver")

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

在 urls.py 中：

...
    path("altmcp", MCPServerStreamableHttpView.as_view(mcp_server=second_server))
...

---

测试

默认情况下，您的 MCP 服务器将以 无状态流式 HTTP 传输 端点的形式在 <your_django_server>/mcp （例如 http://localhost:8000/mcp）可用（*结尾没有 /！*）。

有许多测试方法：

1. 使用测试 MCP 客户端脚本：test/test_mcp_client.py
2. 您可以使用 MCP Inspector 工具 进行测试
3. 或任何兼容的 MCP 客户端。

---

与代理框架和 MCP 客户端的集成

您可以轻松地将 MCP 服务器端点连接到支持 MCP 流式 HTTP 服务器的任何代理框架。 参考此 客户端列表

---

发展路线图

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

---

问题

如果您遇到 bug 或有功能请求，请在 GitHub Issues 上打开一个问题。

---

许可证

MIT 许可证。