Django Mcp Wrapper

PyPI Tests Changelog License

Django views that wrap MCP stdio servers and expose them over Streamable HTTP.

Installation

pip install django-mcp-wrapper

For OAuth 2.0 support (Claude for Web, dynamic client registration):

pip install django-mcp-wrapper[oauth]

Quick Start

Define a wrapper class and mount it at a URL path:

# mcp_wrappers.py
from django_mcp_wrapper import StdioMcpWrapper

class FileSystemMcp(StdioMcpWrapper):
    command = "npx"
    args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

# urls.py
from django.urls import path
from .mcp_wrappers import FileSystemMcp

urlpatterns = [
    path("mcp", FileSystemMcp.as_view()),
]

Override get_command(), get_args(), or get_env() for per-request customization:

class DynamicMcp(StdioMcpWrapper):
    command = "npx"

    def get_args(self):
        directory = os.environ.get("MCP_DIR", os.getcwd())
        return ["-y", "@modelcontextprotocol/server-filesystem", directory]

Mount multiple wrappers at different paths:

urlpatterns = [
    path("desktop/mcp", DesktopMcp.as_view()),
    path("project/mcp", ProjectMcp.as_view()),
]

Authentication

API Key

Override authenticate() to add request-level auth. Return None to allow the request, or an HttpResponse to reject it:

class SecureMcp(StdioMcpWrapper):
    command = "npx"
    args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

    def authenticate(self, request):
        valid_keys = {"my-secret-key"}
        if request.GET.get("apiKey") not in valid_keys:
            return HttpResponse("Invalid API key", status=401)
        return None

See examples/apikey/ for a full working example.

OAuth 2.0 with Dynamic Client Registration (Claude for Web)

For MCP clients that use OAuth (like Claude for Web), django-mcp-wrapper provides RFC 9728 protected resource metadata and bearer token validation, with RFC 7591 dynamic client registration via django-oauth-toolkit-dcr, all backed by django-oauth-toolkit:

# mcp_wrappers.py
from django_mcp_wrapper import StdioMcpWrapper
from django_mcp_wrapper.oauth import bearer_token_authenticate

class OAuthMcp(StdioMcpWrapper):
    command = "npx"
    args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

    def authenticate(self, request):
        return bearer_token_authenticate(request)

# urls.py
from django_mcp_wrapper.oauth import oauth_urlpatterns

urlpatterns = [
    path("mcp", OAuthMcp.as_view()),
    *oauth_urlpatterns(
        resource_url="https://yourserver.com/mcp",
        authorization_server_url="https://yourserver.com/o",
    ),
]

This wires up:

• /.well-known/oauth-protected-resource/mcp — resource metadata (RFC 9728)
• /o/register/ — dynamic client registration (RFC 7591, via django-oauth-toolkit-dcr)
• /o/authorize/, /o/token/ — authorization code + PKCE flow (django-oauth-toolkit)

See examples/oauth/ for a full working example with settings.

Development

cd django-mcp-wrapper
python -m venv venv
source venv/bin/activate
pip install -e '.[dev]'
python -m pytest