# DRF MCP

[![PyPI version](https://badge.fury.io/py/drf-mcp.svg)](https://badge.fury.io/py/drf-mcp)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Django 4.2+](https://img.shields.io/badge/django-4.2+-darkgreen.svg)](https://www.djangoproject.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Enterprise-grade Model Context Protocol (MCP) integration for Django REST Framework with FastMCP 3.0**

Automatically expose your Django REST Framework APIs as tools for AI agents via the Model Context Protocol. Zero configuration, maximum security, enterprise-ready.

## Overview

DRF MCP transforms your Django REST Framework views into AI-native tools via the Model Context Protocol standard. Built on FastMCP 3.0, it automatically:

- 🔍 **Discovers** all DRF views and ViewSets in your Django URLconf
- 🔧 **Exposes** them as MCP tools with auto-generated JSON schemas
- 🔐 **Secures** with DRF's permission system (no security bypass)
- ⚡ **Async-first** execution for non-blocking LLM interactions
- 📊 **Traces** with OpenTelemetry for observability
- 🚀 **Scales** with stateless, transport-agnostic architecture

## Quick Start

```python
# In your Django project
from drf_mcp import DRFMCP
from myapp.views import CustomerViewSet

# Initialize MCP server
mcp = DRFMCP("MyEnterpriseAPI")

# Option 1: Register specific ViewSets
mcp.register_viewset(CustomerViewSet, namespace="crm")

# Option 2: Auto-discover all DRF views
mcp.autodiscover()

# Run server (stdio, HTTP, or SSE transport)
if __name__ == "__main__":
    mcp.run()
```

Your DRF serializers automatically become MCP tool parameters. No extra configuration needed.

## Architecture

### Discovery
Scans Django's URLconf to find all DRF APIView and ViewSet classes.

### Schema Generation
Uses `drf-spectacular` to convert DRF serializers into JSON schemas for MCP tool arguments.

### Execution
Wraps DRF view invocations with async support, permission checking, and error handling.

### Security
Enforces DRF's authentication and permission classes on every tool call. Agents are authenticated users.

### Transport
Supports stdio, HTTP, and SSE via FastMCP's built-in transports.

## Features

- ✅ Automatic DRF view discovery and MCP tool generation
- ✅ drf-spectacular schema integration (nested serializers, complex validators)
- ✅ DRF permission system integration (no security bypass)
- ✅ Async-first executor (non-blocking LLM execution)
- ✅ OAuth2/OIDC agent authentication
- ✅ OpenTelemetry tracing for observability
- ✅ Interactive `manage.py mcp_inspector` CLI
- ✅ Type hints and Pydantic v2 schemas
- ✅ Django 4.2 LTS and 5.0+ support
- ✅ Python 3.10+ support

## Installation

```bash
uv add drf-mcp
```

Or with pip:
```bash
pip install drf-mcp
```

## Documentation

Full documentation is available at [drf-mcp.readthedocs.io](https://drf-mcp.readthedocs.io)

- [Getting Started](docs/guide/getting_started.md)
- [Architecture](docs/guide/architecture.md)
- [Security](docs/guide/security.md)
- [API Reference](docs/api/)
- [Examples](docs/examples/)

## Requirements

- **Python**: 3.10+
- **Django**: 4.2+ (LTS) or 5.0+
- **Django REST Framework**: 3.14+
- **FastMCP**: 3.0+

## Development

```bash
# Clone and setup
git clone https://github.com/ziyacivan/drf-mcp.git
cd drf-mcp
uv venv
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/drf_mcp tests
isort src/drf_mcp tests

# Type checking
mypy src/drf_mcp
```

## License

MIT License - See [LICENSE](LICENSE) file for details.

## Contributing

Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Acknowledgments

- [FastMCP](https://github.com/jlowin/fastmcp) - High-level MCP framework
- [drf-spectacular](https://github.com/tfranzel/drf-spectacular) - OpenAPI schema generation
- [Django REST Framework](https://www.django-rest-framework.org/) - Best-in-class Python API framework
- [gts360/django-mcp-server](https://github.com/gts360/django-mcp-server) - Original reference implementation