Django MCP Server

Una extensión de Django para permitir que agentes de IA interactúen con aplicaciones Django a través del Model Context Protocol.

GitHub

381

Prueba este MCPPatrocinado

Documentación

Django MCP Server

License Python versions

Django MCP Server es una implementación de la extensión del Model Context Protocol (MCP) para Django. Este módulo permite que Clientes MCP y agentes de IA interactúen con cualquier aplicación Django de manera fluida.

🚀 Herramientas declarativas de estilo Django para permitir que agentes de IA y herramientas de clientes MCP interactúen con Django.
🚀 Exponga modelos de Django para que agentes de IA y herramientas MCP los consulten en 2 líneas de código de forma segura.
🚀 Convierta APIs de Django Rest Framework en herramientas MCP con una sola anotación.
✅ Funciona tanto en WSGI como en ASGI sin cambios de infraestructura.
✅ Validado como integración remota con Claude AI.
🤖 Cualquier cliente MCP o agente de IA compatible con MCP (Google Agent Development Kit, Claude AI, Claude Desktop ...) puede interactuar con su aplicación.

Muchas gracias 🙏 a toda la comunidad de contribuyentes

Mantenido ✨ con cuidado por Smart GTS software engineering.

Licenciado bajo la Licencia MIT.

Características

Exponga modelos y lógica de Django como herramientas MCP.
Sirva un endpoint MCP dentro de su aplicación Django.
Integre fácilmente con agentes de IA, clientes MCP o herramientas como Google ADK.

Inicio Rápido

1️⃣ Instalación

pip install django-mcp-server

O directamente desde GitHub:

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

2️⃣ Configurar Django

✅ Agregue mcp_server a su INSTALLED_APPS:

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

✅ Agregue el endpoint MCP a su urls.py:

from django.urls import path, include

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

Por defecto, el endpoint MCP estará disponible en /mcp.

3️⃣ Definir Herramientas MCP

En mcp.py cree una subclase de ModelQueryToolset para dar acceso a un modelo:

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

O cree una subclase de MCPToolset para publicar métodos genéricos (los métodos privados _ no se publican)

Ejemplo:

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='your_email@example.com',
             recipient_list=[to_email],
             fail_silently=False,
         )

Verificar con MCP Inspect

Use el comando de gestión mcp_inspect para asegurarse de que sus herramientas estén declaradas correctamente:

python manage.py mcp_inspect

Usar el MCP con cualquier Cliente MCP

La herramienta mcp ahora está publicada en su aplicación Django en el endpoint /mcp.

IMPORTANTE Para configuraciones de producción, en datos no públicos, considere habilitar la autorización a través de: DJANGO_MCP_AUTHENTICATION_CLASSES

Probar con el SDK de Python de MCP

Puede probarlo con el SDK de Python de MCP:

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())

Reemplace http://localhost:8000/mcp por el host real de Django y ejecute este script.

Usar desde Claude AI

A partir de junio de 2025, Claude AI ahora admite MCP a través del protocolo HTTP transmisible con requisitos previos: *

Configurar OAuth2, por ejemplo:
- Instale Django Oauth Toolkit)
- Incluya 'oauth2_provider.contrib.rest_framework.OAuth2Authentication' en DJANGO_MCP_AUTHENTICATION_CLASSES en settings.py
Claude AI requiere Registro Dinámico de Clientes. Hoy en día no es compatible con django oauth toolkit pero puede usar Este complemento DCR de Django Oauth Toolkit
A menos que implemente los Metadatos del Servidor OAuth RFC correctamente, debe mantener las URL de OAuth2 (/register, /token y /authorize en su ubicación predeterminada).

Probar en Claude Desktop

Puede probar servidores MCP en Claude Desktop. Por ahora, Claude Desktop solo admite servidores MCP locales. Por lo tanto, debe tener su aplicación instalada en la misma máquina, probablemente en un entorno de desarrollo.

Para esto necesita:

Instalar Claude Desktop desde claude.ai
Abrir Archivo > Configuración > Desarrollador y hacer clic en Editar Configuración

Abrir claude_desktop_config.json y configurar su servidor MCP:

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

NOTA /path/to/interpreter/ debe apuntar a un intérprete de Python que use (puede estar en su venv, por ejemplo) y /path/to/your/project/ es la ruta a su proyecto Django.

Temas Avanzados

Publicar APIs de Django Rest Framework como Herramientas MCP

Puede usar drf_publish_create_mcp_tool / drf_publish_update_mcp_tool / drf_publish_delete_mcp_tool / drf_publish_list_mcp_tool como anotaciones o llamadas a métodos para registrar vistas basadas en CreateModelMixin / UpdateModelMixin / DestroyModelMixin / ListModelMixin de DRF como herramientas MCP sin problemas. Django MCP Server generará los esquemas para permitir que los clientes MCP los usen.

NOTA en algunas versiones antiguas de DRF, la generación de esquemas no es compatible de forma nativa, por lo que debe proporcionar a la anotación de registro el

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

tenga en cuenta que el docstring de la vista se usa como instrucciones para el modelo. Puede ajustar esto mejor así:

@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

Finalmente, puede registrar después en mcp.py, por ejemplo, con:

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

IMPORTANTE

Tenga en cuenta que las clases de autenticación integradas están deshabilitadas por defecto junto con filter_backends, permission_classes y pagination_class, porque se usa la autenticación MCP.

Dado que pagination_class también está deshabilitado, deberá tenerlo en cuenta si está usando una vista DRF paginada existente (self.paginator será None).

Integración de Serializadores de Django Rest Framework

Puede anotar una herramienta con drf_serialize_output(...) para serializar su salida usando Django Rest Framework, así:

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()

Usar anotación de servidor MCP de bajo nivel

Puede importar la instancia del servidor DjangoMCP y usar anotaciones FastMCP para declarar herramientas y recursos 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

⚠️ Importante:

Siempre use la API ORM asíncrona de Django cuando defina herramientas asíncronas.
Tenga cuidado de no devolver un QuerySet, ya que se evaluará de forma asíncrona, lo que podría crear errores.

Personalizar la configuración predeterminada del servidor MCP

En settings.py puede inicializar el parámetro DJANGO_MCP_GLOBAL_SERVER_CONFIG. Estos se pasarán al servidor MCPServer durante la inicialización.

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

Gestión de sesiones

Por defecto, el servidor tiene estado, y el estado se gestiona como sesión de Django objeto request.session, por lo que el backend de sesiones debe estar configurado correctamente. El objeto de solicitud está disponible en self.request para conjuntos de herramientas basados en clases.

NOTA No se requiere configurar el middleware de sesiones, ya que las sesiones MCP se gestionan de forma independiente y sin cookies.

Puede hacer que el servidor no tenga estado definiendo: DJANGO_MCP_GLOBAL_SERVER_CONFIG

IMPORTANTE el estado se gestiona mediante sesiones de Django; si usa la anotación de bajo nivel @mcp_server.tool(), por ejemplo, el comportamiento de preservar la instancia del servidor entre llamadas de la API base de Python no se conserva debido a la arquitectura de Django en implementaciones WSGI donde las solicitudes pueden ser atendidas por diferentes hilos.

Autorización

El endpoint MCP admite clases de autorización de Django Rest Framework Puede configurarlas usando DJANGO_MCP_AUTHENTICATION_CLASSES en settings.py, por ejemplo:

DJANGO_MCP_AUTHENTICATION_CLASSES=["rest_framework.authentication.TokenAuthentication"]

IMPORTANTE Ahora la Especificación MCP versión 2025-03-26 recomienda usar un flujo de trabajo OAuth2, por lo que debe integrar la configuración de django-oauth-toolkit con integración de djangorestframework y usar 'oauth2_provider.contrib.rest_framework.OAuth2Authentication' en DJANGO_MCP_AUTHENTICATION_CLASSES. Consulte la documentación oficial de django-oauth-toolkit

Configuración avanzada / personalizada de la vista

Puede montar la vista MCPServerStreamableHttpView.as_view() en su urls.py y personalizarla con cualquier parámetro adicional.

Formato de salida personalizado (renderizadores) para ModelQueryToolset

Puede definir cualquier renderizador de DRF para producir salida; para esto debe declararse en su configuración:

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

Luego, en su declaración ModelQueryToolset puede agregar

    ...
    output_format="csv"

Además, puede indicar a la herramienta que adjunte el resultado como un [Recurso Incrustado de MCP] en lugar de devolverlo directamente con

    ...
    output_as_resource=True

NOTA algunos renderizadores como drf-excel están diseñados de una manera que no permite usarlos fuera de la Vista DRF; no funcionarán aquí.

Endpoint MCP secundario

en mcp.py

from mcp_server.djangomcp import DjangoMCP

second_mcp = DjangoMCP(name="altserver")

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

en urls.py

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

IMPORTANTE Cuando haga esto, la configuración DJANGO_MCP_AUTHENTICATION_CLASSES se ignora y su vista no es segura. DEBE Configurar la Autenticación DRF para su vista, por ejemplo:

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

Pruebas

El servidor

Puede configurar su propia aplicación o usar la aplicación Django de ejemplo mcpexample.

El cliente

Por defecto, su servidor MCP estará disponible como un endpoint de transporte HTTP transmisible sin estado en <your_django_server>/mcp (ej. http://localhost:8000/mcp) (*sin / al final!).

Hay muchas formas de probar:

Usando el script de cliente MCP de prueba: test/test_mcp_client.py
Puede probar usando la herramienta MCP Inspector
o cualquier cliente MCP compatible como Google Agent Development Kit.

Integración con Marcos de Agentes y Clientes MCP

Ejemplo de Google Agent Development Kit

NOTA hoy en día el Google ADK oficial no admite transporte StreamableHTTP pero puede usar este fork

Luego puede usar el agente de prueba en test/test_agent iniciando adk web en la carpeta test. Asegúrese primero:

Instale adk con soporte streamablehttp: pip install git+https://github.com/omarbenhamid/google-adk-python.git
Inicie una aplicación Django con un endpoint MCP: python manage.py runserver en la carpeta examples/mcpexample.
Si usa TokenAuthorization, cree un token de acceso, por ejemplo, en el Administrador de Django de su aplicación.
Configure en test/test_agent/agent.py la ubicación correcta del endpoint y el encabezado de autenticación
Entre a la carpeta test.
Ejecute adk web
En el shell puede usar, por ejemplo, este mensaje: "Vi a Woody Woodpecker, agrégalo a mi inventario"

Otros clientes

Puede conectar fácilmente su endpoint de servidor MCP a cualquier marco de agentes que admita servidores MCP HTTP transmisibles. Consulte esta lista de clientes

Configuración

DJANGO_MCP_GLOBAL_SERVER_CONFIG un diccionario de configuración para el servidor MCP global, por defecto vacío. Puede incluir los siguientes parámetros:
- name: un nombre para el servidor
- instructions: instrucciones globales
- stateless: cuando se establece en 'True', el servidor no gestionará sesiones
DJANGO_MCP_AUTHENTICATION_CLASSES (por defecto sin autenticación) una lista de referencias a clases de autenticación de Django Rest Framework para aplicar en la vista MCP principal.
DJANGO_MCP_GET_SERVER_INSTRUCTIONS_TOOL (por defecto=True) si es verdadero, se ofrecerá una herramienta para obtener instrucciones globales y las herramientas indicarán al agente que la use, ya que los agentes no siempre incluyen las instrucciones globales del servidor MCP en su mensaje de sistema.
DJANGO_MCP_ENDPOINT (por defecto="mcp") una cadena que indica el endpoint de URL utilizado por el servidor. Si desea que tenga una barra diagonal final, por ejemplo, configúrelo en "mcp/"

Hoja de ruta

✅ Transporte HTTP transmisible sin estado (implementado)
🔜 Integración de transporte STDIO para configuración de desarrollo (ej. Claude Desktop)
🔜 ****
🔜 Transporte HTTP transmisible con estado usando sesiones de Django
🔜 Integración de endpoint SSE (requiere ASGI)
🔜 Mejora de gestión de errores y registro

Problemas

Si encuentra errores o tiene solicitudes de funciones, abra un problema en GitHub Issues.

Licencia

Licencia MIT.