Metadata-Version: 2.4
Name: django-mcp-wrapper
Version: 0.1
Summary: Django views that wrap MCP stdio servers and expose them over Streamable HTTP
Author: player1537-playground
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/player1537-playground/django-mcp-wrapper
Project-URL: Changelog, https://github.com/player1537-playground/django-mcp-wrapper/releases
Project-URL: Issues, https://github.com/player1537-playground/django-mcp-wrapper/issues
Project-URL: CI, https://github.com/player1537-playground/django-mcp-wrapper/actions
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django>=4.2
Requires-Dist: mcp>=1.0
Requires-Dist: asgiref
Provides-Extra: oauth
Requires-Dist: django-oauth-toolkit>=2.0; extra == "oauth"
Requires-Dist: django-oauth-toolkit-dcr>=0.1; extra == "oauth"
Dynamic: license-file

# django-mcp-wrapper

[![PyPI](https://img.shields.io/pypi/v/django-mcp-wrapper.svg)](https://pypi.org/project/django-mcp-wrapper/)
[![Tests](https://github.com/player1537-playground/django-mcp-wrapper/actions/workflows/test.yml/badge.svg)](https://github.com/player1537-playground/django-mcp-wrapper/actions/workflows/test.yml)
[![Changelog](https://img.shields.io/github/v/release/player1537-playground/django-mcp-wrapper?include_prereleases&label=changelog)](https://github.com/player1537-playground/django-mcp-wrapper/releases)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/player1537-playground/django-mcp-wrapper/blob/main/LICENSE)

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

## Installation

```bash
pip install django-mcp-wrapper
```

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

```bash
pip install django-mcp-wrapper[oauth]
```

## Quick Start

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

```python
# mcp_wrappers.py
from django_mcp_wrapper import StdioMcpWrapper

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

```python
# 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:

```python
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:

```python
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:

```python
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`](https://pypi.org/project/django-oauth-toolkit-dcr/),
all backed by [`django-oauth-toolkit`](https://django-oauth-toolkit.readthedocs.io/):

```python
# 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)
```

```python
# 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

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