Django MCP Server

0.5.7 verified Sat May 09 auth: no python

Django MCP Server is a Django extension that enables AI Agents to interact with Django Apps through the Model Context Protocol (MCP). It works on both WSGI and ASGI, providing a simple way to expose Django models and views as tools for AI agents. Current version 0.5.7, release cadence is irregular as the library is still in early development.

pip install django-mcp-server

Common errors

error ModuleNotFoundError: No module named 'django_mcp_server' ↓

cause Package not installed or wrong import path.

fix

Run 'pip install django-mcp-server' and ensure you imported 'django_mcp_server' (underscore, not hyphen).

error AttributeError: module 'django_mcp_server' has no attribute 'tools' ↓

cause tools is a decorator in the decorators submodule, not directly on the package.

fix

Change import to 'from django_mcp_server.decorators import tools'

error TypeError: register() missing 1 required positional argument: 'func' ↓

cause The @tools.register decorator was used without parentheses, but the syntax requires parentheses when passing arguments (e.g., name).

fix

Use '@tools.register' without parentheses if no arguments, or '@tools.register(name="...")' with parentheses if needed.

error RuntimeError: MCP endpoint requires a Django HttpRequest object. ↓

cause The tool function received a non-request object, likely from an external HTTP call that bypassed Django middleware.

fix

Ensure the MCP server is mounted inside Django's URLconf so that request objects are properly constructed.

Warnings

breaking In version 0.5.x, the MCPServer class moved from django_mcp_server.server to django_mcp_server directly. If you import from the old path, it will break. ↓

fix Change imports to 'from django_mcp_server import MCPServer'

deprecated The @tools.register decorator signature changed in v0.5.4: the 'name' parameter is deprecated. Use the function name directly. ↓

fix Remove name argument; if you need a custom name, use the @mcp_tool decorator instead

gotcha When using the @tools.register decorator, the first argument must be a request object (HttpRequest), not a plain dictionary. Many users mistakenly pass a dict from an external API call. ↓

fix Ensure the tool function signature is 'def my_tool(request, ...)'

gotcha The MCP endpoint expects POST requests with Content-Type application/json. Some users try to access the endpoint via GET, resulting in a 405 Method Not Allowed error. ↓

fix Use a tool like curl with -X POST -H 'Content-Type: application/json'

Install

pip install django-mcp-server[uvicorn]

Imports

MCPServer
wrong
```
from django_mcp import MCPServer
```
correct
```
from django_mcp_server import MCPServer
```
Incorrect module name; the package is 'django_mcp_server'

tools

wrong

from django_mcp_server import tools

correct

from django_mcp_server.decorators import tools

tools is a decorator in the decorators module

mcp_tool

from django_mcp_server.decorators import mcp_tool

Quickstart

Create an MCP endpoint at /mcp/ exposing Django ORM tools.

# In your Django app's models.py or mcp.py
from django_mcp_server import MCPServer
from django_mcp_server.decorators import tools

mcp_server = MCPServer()

@tools.register
def get_product_count(request) -> int:
    """Return the number of products in the database."""
    from myapp.models import Product
    return Product.objects.count()

# In urls.py
from django.urls import path
from . import mcp

urlpatterns = [
    path('mcp/', mcp.mcp_server.urls),
]

# Then run with ASGI (uvicorn) or WSGI
# uvicorn myproject.asgi:application --reload