djangorestframework-mcp-server
Expose djangorestframework-services
services and selectors as a Model Context Protocol
(MCP) server, conforming to MCP 2026-07-28 and 2025-11-25 (Streamable HTTP).
Idea
Register ServiceSpec instances directly — no DRF router or viewset
involvement. The unit of registration is the ServiceSpec, not a view.
from django.urls import path
from django_service_specs import SelectorKind
from rest_framework_services.types.selector_spec import SelectorSpec
from rest_framework_services.types.service_spec import ServiceSpec
from rest_framework_mcp import MCPServer
server = MCPServer(name="my-app")
server.register_service_tool(
name="invoices.create",
spec=ServiceSpec(
service=create_invoice,
input_serializer=InvoiceInputSerializer,
output_selector_spec=SelectorSpec(
kind=SelectorKind.RETRIEVE,
output_serializer=InvoiceOutputSerializer,
),
),
)
server.register_resource(
name="invoice",
uri_template="invoices://{pk}",
selector=SelectorSpec(
kind=SelectorKind.RETRIEVE,
selector=get_invoice,
output_serializer=InvoiceOutputSerializer,
),
)
urlpatterns = [path("mcp/", server.urls)]
A decorator form is also supported (@server.service_tool(...) / @server.resource(...)).
See the quickstart for the full end-to-end recipe.
- Services (mutations) → MCP tools.
- Selectors (reads) → MCP resources.
- A single
/mcpendpoint speaks Streamable HTTP. The/.well-known/oauth-protected-resourceendpoint comes mounted alongside.
What ships
- Tools —
tools/list,tools/callforregister_service_tool(mutations) andregister_selector_tool(reads, with optionalFilterSet+ ordering + pagination). - Server-supplied arguments —
server_arguments=ServerArguments(values=..., withheld=...)at registration answers a declared argument for the caller: the name leaves the tool's schema, a caller's value for it is dropped and logged by name, and the binding is checked when it is registered. Route and query values a tool asks for are read from the spec's ownreads. - Resources —
resources/list,resources/templates/list,resources/readagainstSelectorSpec-backed callables; RFC 6570 templated URIs. - Prompts —
prompts/list,prompts/getagainst render callables returning strings,PromptMessages, or async coroutines. - In-process transport surface — call tools without an HTTP round-trip:
MCPServer.call_tool/acall_toolandlist_tools/alist_toolsdrive the same dispatch and permission checks as the wire path, for embedding in agent bridges, toolsets, or management commands.unavailable_tools/aunavailable_toolsname each tool the listing leaves out with the reason, so a bridge can tell its model why one is missing. - Tool annotations — pass
annotations=at registration (or rely on the read/mutation default) to advertise MCP hints likereadOnlyHint/destructiveHintontools/list. - Generic
_meta— passmeta=at registration to populate the base protocol's free-form_metaobject on a tool, resource, or prompt's listing entry (and on thecontentsofresources/read). Passed through verbatim, so protocol extensions have somewhere to live. - Interactive views (MCP Apps) —
register_ui_resource(...)declares an HTML view with typed CSP / permission metadata;ui=UIToolMeta(...)on a tool links its result to that view, and a host renders it inline in the chat. The render payload is thestructuredContentyou already emit, and a view's owntools/calls inherit your auth, permissions and rate limits. An extension over base MCP, so no protocol bump. We declare; the host sandboxes and renders. - Pluggable auth —
DjangoOAuthToolkitBackend(default) andAllowAnyBackend(dev only). Per-bindingMCPPermissionclasses (ScopeRequired,DjangoPermRequired) plus your own. - RFC 8707 audience binding when
RESOURCE_URLis configured; RFC 9728 PRM served from the configured backend. - Per-binding rate limits —
MCPRateLimitProtocol withFixedWindowRateLimit,SlidingWindowRateLimit, andTokenBucketRateLimitimplementations shipped. - Output formats — JSON (default) and TOON (token-oriented; optional extra with safe JSON fallback).
- Async POST/DELETE + GET-side SSE push — sync
urlsfor WSGI,async_urlsfor ASGI;MCPServer.notify(session_id, payload)pushes JSON-RPC frames on the session's SSE stream. Per-workerInMemorySSEBrokeror cross-workerRedisSSEBroker(behind[redis]);Last-Event-IDresume viaInMemorySSEReplayBuffer/RedisSSEReplayBuffer. - OpenTelemetry instrumentation —
mcp.tools.call,mcp.resources.read,mcp.prompts.getspans (no-op without the[otel]extra installed). - Origin allowlist + protocol-version validation + session
lifecycle per the transport rules of both revisions.
2026-07-28and later declare version, identity and capabilities on every request and hold no session;2025-11-25and earlier negotiate once throughinitialize. Both are served concurrently on one endpoint, because a legacy client has no fall-forward mechanism.
Install
pip install djangorestframework-mcp-server # JSON only
pip install "djangorestframework-mcp-server[toon]" # +TOON encoder
pip install "djangorestframework-mcp-server[oauth]" # +django-oauth-toolkit backend
pip install "djangorestframework-mcp-server[redis]" # +Redis SSE broker for multi-worker ASGI
pip install "djangorestframework-mcp-server[otel]" # +OpenTelemetry instrumentation
pip install "djangorestframework-mcp-server[filter]" # +django-filter for selector-tool FilterSets
pip install "djangorestframework-mcp-server[spectacular]" # +drf-spectacular schema overrides
pip install "djangorestframework-mcp-server[jwt]" # +SimpleJWTCookieAdapter (djangorestframework-simplejwt)
pip install "djangorestframework-mcp-server[toon,oauth,redis,otel,filter,spectacular,jwt]" # everything
…or with uv:
uv add djangorestframework-mcp-server # JSON only
uv add "djangorestframework-mcp-server[toon]" # +TOON encoder
uv add "djangorestframework-mcp-server[oauth]" # +django-oauth-toolkit backend
uv add "djangorestframework-mcp-server[redis]" # +Redis SSE broker for multi-worker ASGI
uv add "djangorestframework-mcp-server[otel]" # +OpenTelemetry instrumentation
uv add "djangorestframework-mcp-server[filter]" # +django-filter for selector-tool FilterSets
uv add "djangorestframework-mcp-server[spectacular]" # +drf-spectacular schema overrides
uv add "djangorestframework-mcp-server[jwt]" # +SimpleJWTCookieAdapter (djangorestframework-simplejwt)
uv add "djangorestframework-mcp-server[toon,oauth,redis,otel,filter,spectacular,jwt]" # everything
Optional extras degrade gracefully: TOON falls back to JSON with a runtime
warning if python-toon is not installed, and the OAuth backend module imports
cleanly without oauth2_provider, so a server used in process needs no DOT.
Mounting one over HTTP refuses without it, while the URLConf is imported.
Try it
Install mcp-inspector and point it at your dev server:
npx @modelcontextprotocol/inspector --url http://localhost:8000/mcp/
Inspector lists tools, fills in arguments from the generated JSON Schema, and walks the OAuth auth flow against your configured Authorization Server.
Documentation
- Quickstart — copy-pasteable end-to-end.
- Concepts — tools vs resources, sessions, output formats.
- Authentication — backends, permissions, audience binding, bring-your-own AS recipe.
- Recipes — focused cookbook entries.
- Reference — autodocs for every public symbol.
License
MIT.
1 maintainer
Metadata
1 maintainer
Release files for djangorestframework-mcp-server 0.53.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| djangorestframework_mcp_server-0.53.1.tar.gz | 1.2 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| djangorestframework_mcp_server-0.53.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.7 MB
Release files / djangorestframework_mcp_server-0.53.1.tar.gz
| Download URL | djangorestframework_mcp_server-0.53.1.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
39a9d767274776bfb923db0d993ce9decb819607939503fd0a1d385dea0d7eda
|
|
BLAKE2b-256 checksum How to use checksums |
49efb7bee9c8f71d9b1b3a8ab81003632a6222902036a6b3783f5b21000fcb94
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logRelease files / djangorestframework_mcp_server-0.53.1-py3-none-any.whl
| Download URL | djangorestframework_mcp_server-0.53.1-py3-none-any.whl |
|---|---|
| Size | 512.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d58cc9a0f2481fd26b8ee1a9408b38c96f7e0249ee7eb3636708f8f0e2418e30
|
|
BLAKE2b-256 checksum How to use checksums |
3428babcbb6b160908b7bc433179d7d02088690ee3145c9f8ba046cf9e678327
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logSecurity for djangorestframework-mcp-server 0.53.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for djangorestframework_mcp_server-0.53.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
