Django MCP Server

Uma extensão Django para permitir que agentes de IA interajam com aplicativos Django através do Model Context Protocol.

GitHub
371
Experimente este MCPPatrocinado

Documentação

Django MCP Server

PyPI version License Published on Django Packages Python versions Django versions

Django MCP Server é uma implementação da extensão Model Context Protocol (MCP) para Django. Este módulo permite que clientes MCP e agentes de IA interajam com qualquer aplicação Django de forma transparente.

🚀 Ferramentas declarativas no estilo Django para permitir que agentes de IA e clientes MCP interajam com Django.
🚀 Exponha modelos Django para agentes de IA e ferramentas MCP consultarem em 2 linhas de código de forma segura.
🚀 Converta APIs Django Rest Framework em ferramentas MCP com uma anotação.
✅ Funciona em WSGI e ASGI sem mudança de infraestrutura.
✅ Validado como integração remota com Claude AI.
🤖 Qualquer cliente MCP ou agente de IA que suporte MCP (Google Agent Development Kit, Claude AI, Claude Desktop ...) pode interagir com sua aplicação.

Muitos agradecimentos 🙏 a toda a comunidade de contribuidores

Mantido ✨ com cuidado por Smart GTS software engineering.

Licenciado sob a Licença MIT.

Recursos

  • Exponha modelos e lógica do Django como ferramentas MCP.
  • Sirva um endpoint MCP dentro da sua aplicação Django.
  • Integre facilmente com agentes de IA, clientes MCP ou ferramentas como Google ADK.

Início Rápido

1️⃣ Instalação

pip install django-mcp-server

Ou diretamente do GitHub:

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

2️⃣ Configurar Django

✅ Adicione mcp_server ao seu INSTALLED_APPS:

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

✅ Adicione o endpoint MCP ao seu urls.py:

from django.urls import path, include

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

Por padrão, o endpoint MCP estará disponível em /mcp.

3️⃣ Definir Ferramentas MCP

Em mcp.py, crie uma subclasse de ModelQueryToolset para dar acesso a um 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

Ou crie uma subclasse de MCPToolset para publicar métodos genéricos (métodos privados _ não são publicados)

Exemplo:

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 com MCP Inspect

Use o comando de gerenciamento mcp_inspect para garantir que suas ferramentas estejam declaradas corretamente:

python manage.py mcp_inspect

Usar o MCP com qualquer Cliente MCP

A ferramenta mcp agora está publicada na sua aplicação Django no endpoint /mcp.

IMPORTANTE Para configuração em produção, em dados não públicos, considere habilitar a autorização por meio de: DJANGO_MCP_AUTHENTICATION_CLASSES

Testar com o SDK Python do MCP

Você pode testá-lo com o SDK Python do 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())

Substitua http://localhost:8000/mcp pelo host real do Django e execute este script.

Usar a partir do Claude AI

A partir de junho de 2025, o Claude AI agora suporta MCPs por meio do protocolo HTTP streamable com pré-requisitos: *

  • Configure OAuth2, por exemplo:
    • Instale o Django OAuth Toolkit)
    • Inclua 'oauth2_provider.contrib.rest_framework.OAuth2Authentication' em DJANGO_MCP_AUTHENTICATION_CLASSES em settings.py
  • O Claude AI exige Registro Dinâmico de Cliente. Até hoje, não é suportado pelo django oauth toolkit, mas você pode usar Este Add-On DCR do Django OAuth Toolkit
  • A menos que você implemente corretamente o RFC de Metadados do servidor OAuth, você precisa manter as URLs OAuth2 (/register, /token e /authorize em seus locais padrão).

Testar no Claude Desktop

Você pode testar servidores MCP no Claude Desktop. Por enquanto, o Claude Desktop só suporta servidores MCP locais. Portanto, você precisa ter sua aplicação instalada na mesma máquina, provavelmente em um ambiente de desenvolvimento.

Para isso, você precisa:

  1. Instalar o Claude Desktop a partir de claude.ai
  2. Abra Arquivo > Configurações > Desenvolvedor e clique em Editar Configuração
  3. Abra claude_desktop_config.json e configure seu servidor MCP: 
    {
 "mcpServers": {
     "test_django_mcp": {
         "command": "/path/to/interpreter/python",
         "args": [
             "/path/to/your/project/manage.py",
             "stdio_server"
         ]
     }
 }

NOTA /path/to/interpreter/ deve apontar para um interpretador Python que você usa (pode ser no seu venv, por exemplo) e /path/to/your/project/ é o caminho para o seu projeto Django.

Tópicos Avançados

Publicar APIs do Django Rest Framework como Ferramentas MCP

Você pode usar drf_publish_create_mcp_tool / drf_publish_update_mcp_tool / drf_publish_delete_mcp_tool / drf_publish_list_mcp_tool como anotações ou chamadas de método para registrar views baseadas em CreateModelMixin / UpdateModelMixin / DestroyModelMixin / ListModelMixin do DRF como ferramentas MCP de forma transparente. O Django MCP Server gerará os esquemas para permitir que os clientes MCP os utilizem.

NOTA em algumas versões mais antigas do DRF, a geração de esquemas não é suportada nativamente; você deve então fornecer à anotação de registro o

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

observe que o docstring da view é usado como instruções para o modelo.

Você pode ajustar melhor isso assim:

@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, você pode registrar posteriormente em mcp.py, por exemplo, com:

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

IMPORTANTE

Observe que as classes de autenticação integradas são desabilitadas por padrão, juntamente com filter_backends, permission_classes e pagination_class, porque a autenticação MCP é usada.

Como a pagination_class também está desabilitada, você precisará levar isso em conta se estiver usando uma view DRF paginada existente (self.paginator será None).

Integração com Serializer do Django Rest Framework

Você pode anotar uma ferramenta com drf_serialize_output(...) para serializar sua saída usando o Django Rest Framework, por exemplo:

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 anotação de servidor MCP de baixo nível

Você pode importar a instância do servidor DjangoMCP e usar anotações FastMCP para declarar ferramentas e 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:

  1. Sempre use a API ORM assíncrona do Django ao definir ferramentas assíncronas.
  2. Tenha cuidado para não retornar um QuerySet, pois ele será avaliado assincronamente, o que criaria erros.

Personalizar as configurações padrão do servidor MCP

Em settings.py, você pode inicializar o parâmetro DJANGO_MCP_GLOBAL_SERVER_CONFIG. Eles serão passados para o servidor MCPServer durante a inicialização

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

Gerenciamento de sessão

Por padrão, o servidor é stateful, e o estado é gerenciado como objeto sessão do Django request.session, portanto, o backend de sessão deve ser configurado corretamente. O objeto de requisição está disponível em self.request para conjuntos de ferramentas baseados em classes.

NOTA O middleware de sessão não precisa ser configurado, pois as sessões MCP são gerenciadas de forma independente e sem cookies. . Você pode tornar o servidor sem estado definindo: DJANGO_MCP_GLOBAL_SERVER_CONFIG

IMPORTANTE o estado é gerenciado por sessões do Django; se você usar anotação de baixo nível @mcp_server.tool(), por exemplo, o comportamento de preservar a instância do servidor entre chamadas da API Python base não é preservado devido à arquitetura do Django em implantações WSGI, onde as requisições podem ser atendidas por threads diferentes!

Autorização

O endpoint MCP suporta classes de autorização do Django Rest Framework. Você pode defini-las usando DJANGO_MCP_AUTHENTICATION_CLASSES em settings.py, ex.:

DJANGO_MCP_AUTHENTICATION_CLASSES=["rest_framework.authentication.TokenAuthentication"]

IMPORTANTE Agora, a Especificação MCP versão 2025-03-26 recomenda usar um fluxo OAuth2, então você deve integrar a configuração do django-oauth-toolkit com integração djangorestframework e usar 'oauth2_provider.contrib.rest_framework.OAuth2Authentication' em DJANGO_MCP_AUTHENTICATION_CLASSES. Consulte a documentação oficial do django-oauth-toolkit

Configuração avançada / personalizada da view

Você pode, no seu urls.py, montar a view MCPServerStreamableHttpView.as_view() e personalizá-la com quaisquer parâmetros extras.

Formato de saída personalizado (renderers) para ModelQueryToolset

Você pode definir qualquer renderer do DRF para produzir saída; para isso, ele deve ser declarado nas suas configurações:

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

Então, na sua declaração ModelQueryToolset, você pode adicionar

    ...
    output_format="csv"

além disso, você pode instruir a ferramenta a anexar o resultado como um [Recurso Embutido do MCP] em vez de retorno direto com

    ...
    output_as_resource=True

NOTA alguns renderers, como drf-excel, são projetados de uma forma que não permite usá-los fora da View do DRF; eles não funcionarão aqui..

Endpoint MCP secundário

em mcp.py

from mcp_server.djangomcp import DjangoMCP

second_mcp = DjangoMCP(name="altserver")

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

em urls.py

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

IMPORTANTE Ao fazer isso, a configuração DJANGO_MCP_AUTHENTICATION_CLASSES é ignorada e sua view fica insegura. Você DEVE configurar a autenticação do DRF para sua view, por exemplo:

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

Testes

O servidor

Você pode configurar sua própria aplicação ou usar a aplicação Django mcpexample.

O cliente

Por padrão, seu servidor MCP estará disponível como um endpoint de transporte HTTP streamable sem estado em <your_django_server>/mcp (ex. http://localhost:8000/mcp) (*sem / no final!).

Existem muitas maneiras de testar:

  1. Usando o script de teste do cliente MCP: test/test_mcp_client.py
  2. Você pode testar usando a ferramenta MCP Inspector
  3. ou qualquer cliente MCP compatível, como o Google Agent Development Kit.

Integração com Frameworks de Agentes e Clientes MCP

Exemplo com Google Agent Development Kit

NOTA até hoje, o Google ADK oficial não suporta transporte StreamableHTTP, mas você pode usar este fork

Então você pode usar o agente de teste em test/test_agent iniciando adk web na pasta test. Certifique-se primeiro:

  1. Instale o ADK com suporte a streamablehttp: pip install git+https://github.com/omarbenhamid/google-adk-python.git
  2. Inicie uma aplicação Django com um endpoint MCP: python manage.py runserver na pasta examples/mcpexample.
  3. Se você usar TokenAuthorization, crie um token de acesso, por exemplo, no Admin do Django da sua aplicação.
  4. Configure em test/test_agent/agent.py o local correto do endpoint e o cabeçalho de autenticação
  5. Entre na pasta test.
  6. Execute adk web
  7. No shell, você pode, por exemplo, usar este prompt: "Eu vi o pica-pau Woody, adicione-o ao meu inventário"

Outros clientes

Você pode facilmente conectar seu endpoint de servidor MCP a qualquer framework de agentes que suporte servidores HTTP streamable MCP. Consulte esta lista de clientes

Configurações

  • DJANGO_MCP_GLOBAL_SERVER_CONFIG um dicionário de configuração para o servidor MCP global, padrão vazio. Pode incluir os seguintes parâmetros

    • name: um nome para o servidor
    • instructions: instruções globais
    • stateless: quando definido como 'True', o servidor não gerenciará sessões

  • DJANGO_MCP_AUTHENTICATION_CLASSES (padrão: sem autenticação) uma lista de referências a classes de autenticação do Django Rest Framework para aplicar na view MCP principal.

  • DJANGO_MCP_GET_SERVER_INSTRUCTIONS_TOOL (padrão=True) se verdadeiro, uma ferramenta será oferecida para obter instruções globais e as ferramentas instruirão o agente a usá-la, pois os agentes nem sempre têm as instruções globais do servidor MCP incluídas no prompt do sistema.

  • DJANGO_MCP_ENDPOINT (padrão="mcp") uma string indicando o endpoint de URL usado pelo servidor. Se você quiser que tenha uma barra final, por exemplo, defina como "mcp/"

Roteiro

  • ✅ Transporte HTTP streamable sem estado (implementado)
  • 🔜 Integração de transporte STDIO para configuração de desenvolvimento (ex. Claude Desktop)
  • 🔜 ****
  • 🔜 Transporte HTTP streamable com estado usando sessões do Django
  • 🔜 Integração de endpoint SSE (requer ASGI)
  • 🔜 Melhor gerenciamento de erros e registro de logs

Problemas

Se você encontrar bugs ou tiver solicitações de recursos, abra uma issue em GitHub Issues.

Licença

Licença MIT.