Django MCP Server

How to use

Set up a local MCP server inside your Django project and expose tools that map to models or custom functions. Your MCP endpoint will be available at a dedicated path and can be consumed by MCP clients or AI agents. You can test tools locally, secure the endpoint, and publish DRF-based APIs as MCP tools for seamless interaction.

How to install

pip install django-mcp-server

Additional topics

Below are practical setup details you will use to configure and operate your MCP server within Django. Follow these steps to enable the MCP endpoint, declare tools, and secure access.

# 1) Install in your Django environment
# (shown above in the install snippet)

# 2) Configure Django
INSTALLED_APPS = [
    # your apps...
    'mcp_server',
]

# 3) Expose MCP endpoint in urls.py
from django.urls import path, include
urlpatterns = [
    # your urls...
    path("", include('mcp_server.urls')),
]

# By default, the MCP endpoint is available at /mcp

# 4) Define MCP Tools in your mcp.py
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

Security and testing

Protect the MCP endpoint using Django Rest Framework authentication classes and project settings. If you need a stateless setup for development, you can configure DJANGO_MCP_GLOBAL_SERVER_CONFIG accordingly. Test tooling and connections with the included MCP Inspector or a compatible MCP client to ensure access control and tool behavior meet your needs.

python manage.py mcp_inspect

Configuration and examples

You can customize server behavior and orchestration through Django settings. For example, you can provide a global server config, specify authentication classes, and choose the endpoint path.

# In settings.py
DJANGO_MCP_GLOBAL_SERVER_CONFIG = {
    "name": "mymcp",
    "instructions": "Some instructions to use this server",
    "stateless": False
}

DJANGO_MCP_AUTHENTICATION_CLASSES = ["rest_framework.authentication.TokenAuthentication"]
DJANGO_MCP_ENDPOINT = "mcp"  # or "mcp/" for a trailing slash

Tools and examples from the source implementations

You can publish and reuse a variety of MCP tools based on Django models, custom toolsets, and DRF-based views. Some example tool names and capabilities you might implement include querying models with filters, performing generic math or utility functions, and sending notifications.

# Example tool names and purposes you may implement
class BirdQueryTool(ModelQueryToolset):
    model = Bird

class LocationTool(ModelQueryToolset):
    model = Location

class CityTool(ModelQueryToolset):
    model = City

class MyAITools(MCPToolset):
    def add(self, a: int, b: int) -> int:
        return a + b

    def send_email(self, to_email: str, subject: str, body: str):
        pass  # implement sending email

Advanced usage notes

You can publish DRF APIs as MCP tools using specific DRF helper decorators, and you can customize how tool results are rendered or embedded as resources. You can also create a secondary MCP endpoint for specialized tooling and secure it with appropriate authentication.

from mcp_server import drf_publish_create_mcp_tool

@drf_publish_create_mcp_tool
class MyModelView(CreateAPIView):
    serializer_class = MySerializer
    
    # docstring is used as tool instructions

CLI and testing helpers

Test the MCP server locally using the standard Django management command and a streamable HTTP or STDI/O transport. Use a MCP client like the Python SDK or Claude-compatible tooling to connect to your /mcp endpoint.

BirdQueryTool

A ModelQueryToolset subclass exposing the Bird model with a filtered queryset for non-null locations.

LocationTool

A ModelQueryToolset exposing the Location model.

CityTool

A ModelQueryToolset exposing the City model.

MyAITools.add

A generic published tool that adds two numbers together.

MyAITools.send_email

A tool to send emails using Django's email facilities.

get_species_count

An async MCP tool that finds the bird species by partial name and returns its count, creating a new entry if needed.

increment_species

An async MCP tool that increments the count of a bird species and saves the change.

drf_publish_create_mcp_tool

Annotation to register DRF CreateModelMixin based views as MCP tools.

drf_serialize_output

Annotation to serialize tool output using a DRF serializer.

mcp_server.tool

Low level FastMCP annotation to declare tools and resources on the server.

second_mcp.tool

Example of a secondary MCP endpoint tool for an alternate server.