zacharypodbela/django-rest-framework-mcp

django-rest-framework-mcp allows you to spin up MCP servers that expose your Django Rest Framework APIs as MCP tools with just a few lines of code.
Supercharge your admin workflows (and make developing Admin interfaces a thing of the past):
- "Deactivate josh@gmail.com's account" → Actually deactivates it
- "Extend jack@teams.com's free trial by 1 week" → Updates their plan
- "How many new users joined week-over-week?" → Returns real data → LLMs can quickly create graphs _(no more complex FE graphing libraries needed)_
Or transform your traditional, boring SaaS UX with conversational interactions:
- Old way: User Clicks "Manage", Clicks "My Posts", Clicks a post from the list, Clicks "Edit", changes the title, Clicks "Save"
- With Django Rest Framework MCP: "Can you rename my post from 'Beginners Guide to Django' to 'Django 101'?"
Quick Start
1. Install the package:
2. Add to your INSTALLED_APPS:
3. Add the MCP endpoint to your urls.py:
4. Transform any DRF ViewSet into MCP tools with a single decorator:
When @mcp_viewset is applied to a ViewSet class that inherits from GenericViewSet (such as ModelViewSet or ReadOnlyModelViewSet), any of the following methods that are defined will be automatically exposed as MCP tools:
- list -> List customers with customers_list tool.
- retrieve -> Retrieve a customer with customers_retrieve tool.
- create -> Create new customers with customers_create tool.
- update -> Update customers with customers_update tool. (All fields must be passed in)
- partial_update -> Update customers with customers_partial_update tool. (A subset of fields can be passed in)
- destroy -> Delete customers with customers_destroy tool.
For each tool the library automatically:
- Generates tool schemas from your DRF serializers
- Preserves your existing permissions, authentication, and filtering
- Returns context rich error messages to guide LLMs
(See: _Custom Actions_ below for more info on how to expose additional endpoints you created using the @action decorator as tools).
5. Connect any MCP client to http://localhost:8000/mcp/ and try it out!
Important Differences between MCP Requests and API Requests
MCP requests do not go through the full DRF request lifecycle.
**View lifecycle methods that will be called:**
- **perform_authentication(request)** - Called unless BYPASS_VIEWSET_AUTHENTICATION = True
- **check_permissions(request)** - Called unless BYPASS_VIEWSET_PERMISSIONS = True
- **check_throttles(request)** - Always called (no bypass option)
- **determine_version(request, \*args, **kwargs)\*\* - Always called to set request versioning
**View lifecycle methods that won't be called:**
- **dispatch(request, args, kwargs)** - will not be called since we don't use HTTP method+path routing.
- **initialize_request(request, args, kwargs)** will not be called. We do create a rest_framework.requests.Request from the django.http.HttpRequest, but not using this handler.
- **initial(request, args, kwargs)** - will not be called.
- **perform_content_negotiation(request)** - will not be called since MCP/JSON-RPC dictates the input and output format.
- **finalize_response(request, response, args, kwargs)** will not be called.
- **handle_exception(exc)** will not be called in the event of an exception\*.
**Additional considerations:**
- The request object will be missing API-specific properties like method, path, or path_info since it wasn't created from an actual HTTP API call
- Content negotiation is bypassed since MCP always uses JSON
Connecting a STDIO MCP Client
Right now, the MCP server is only open to HTTP transport. To support stdio transport, you'll need a bridge. We recommend mcp-remote.
Example: Connect to Claude Desktop
Follow these instructions to use mcp-remote to connect to Claude Desktop:
1. Install mcp-remote: npm install -g mcp-remote
2. Open Claude MCP Desktop Configuration by going to Settings > Developer > Edit Config and add your server configuration:
3. Restart Claude Desktop and test your tools
**Development Tip:** LLMs can be surprisingly effective at “manually” testing your MCP tools and uncovering bugs. In Claude Desktop, try a prompt like: _"I'm developing a new set of MCP tools locally. Please extensively test them — including coming up with complex edge cases to try - and look for unexpected behavior or bugs. Make at least 30 tool calls."_