djangorestframework-mcp-server

CI PyPI Python versions Django versions Docs Coverage Ruff License

Expose djangorestframework-services services and selectors as a Model Context Protocol (MCP) server, conforming to MCP 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 rest_framework_services.types.selector_kind 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 /mcp endpoint speaks Streamable HTTP. The /.well-known/oauth-protected-resource endpoint comes mounted alongside.

What ships

  • Tools — tools/list, tools/call for register_service_tool (mutations) and register_selector_tool (reads, with optional FilterSet + ordering + pagination).
  • Resources — resources/list, resources/templates/list, resources/read against SelectorSpec-backed callables; RFC 6570 templated URIs.
  • Prompts — prompts/list, prompts/get against render callables returning strings, PromptMessages, or async coroutines.
  • In-process transport surface — call tools without an HTTP round-trip: MCPServer.call_tool / acall_tool and list_tools / alist_tools drive the same dispatch and permission checks as the wire path, for embedding in agent bridges, toolsets, or management commands.
  • Tool annotations — pass annotations= at registration (or rely on the read/mutation default) to advertise MCP hints like readOnlyHint / destructiveHint on tools/list.
  • Generic _meta — pass meta= at registration to populate the base protocol's free-form _meta object on a tool, resource, or prompt's listing entry (and on the contents of resources/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 the structuredContent you already emit, and a view's own tools/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) and AllowAnyBackend (dev only). Per-binding MCPPermission classes (ScopeRequired, DjangoPermRequired) plus your own.
  • RFC 8707 audience binding when RESOURCE_URL is configured; RFC 9728 PRM served from the configured backend.
  • Per-binding rate limits — MCPRateLimit Protocol with FixedWindowRateLimit, SlidingWindowRateLimit, and TokenBucketRateLimit implementations shipped.
  • Output formats — JSON (default) and TOON (token-oriented; optional extra with safe JSON fallback).
  • Async POST/DELETE + GET-side SSE push — sync urls for WSGI, async_urls for ASGI; MCPServer.notify(session_id, payload) pushes JSON-RPC frames on the session's SSE stream. Per-worker InMemorySSEBroker or cross-worker RedisSSEBroker (behind [redis]); Last-Event-ID resume via InMemorySSEReplayBuffer / RedisSSEReplayBuffer.
  • OpenTelemetry instrumentation — mcp.tools.call, mcp.resources.read, mcp.prompts.get spans (no-op without the [otel] extra installed).
  • Origin allowlist + protocol-version validation + session lifecycle per the 2025-11-25 transport rules.

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 — the ImportError only fires when you actually configure it.

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.

Project links

Data verified by PyPI on Aug 10, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.42.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for artooi from gravatar.com artooi

Credits

Author: Artur Veres

GitHub Statistics

Data verified by PyPI on Aug 10, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

filter jwt oauth otel redis spectacular toon

Tags

ai django drf llm mcp model-context-protocol rest-framework

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

djangorestframework_mcp_server-0.28.1.tar.gz (766.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

djangorestframework_mcp_server-0.28.1-py3-none-any.whl (414.9 kB view details)

Uploaded Python 3

File details

Details for the file djangorestframework_mcp_server-0.28.1.tar.gz.

File metadata

File hashes

Hashes for djangorestframework_mcp_server-0.28.1.tar.gz
Algorithm Hash digest
SHA256 317e86db0597b9e5761c0c5fd15d4e0047ef011224672e13436a073ad25f3ced
MD5 ae88faf883c5be96f1dc7de944b00b48
BLAKE2b-256 556b8211359d4798b9d6011d202af15b4f500caf9fb631d45e91e41c79405baa

See more details on using hashes here.

Provenance

The following attestation bundles were made for djangorestframework_mcp_server-0.28.1.tar.gz:

Publisher: release.yml on Artui/djangorestframework-mcp-server

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file djangorestframework_mcp_server-0.28.1-py3-none-any.whl.

File metadata

File hashes

Hashes for djangorestframework_mcp_server-0.28.1-py3-none-any.whl
Algorithm Hash digest
SHA256 f7de375972dcd85a6151f385627db9a4b2920d23b2dd584edfff4fbf5a117e13
MD5 35162c565a48d0a57a839cf1777fdba7
BLAKE2b-256 de9fbf4c90789f65ea8257e99e27fc6541ba7530fa61b10274e246c5910e7bd5

See more details on using hashes here.

Provenance

The following attestation bundles were made for djangorestframework_mcp_server-0.28.1-py3-none-any.whl:

Publisher: release.yml on Artui/djangorestframework-mcp-server

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.42.0

2 files

0.41.0

2 files

0.40.1

2 files

0.40.0

2 files

0.39.0

2 files

0.38.0

2 files

0.37.0

2 files

0.36.0

2 files

0.35.0

2 files

0.34.0

2 files

0.33.0

2 files

0.32.1

2 files

0.32.0

2 files

0.31.0

2 files

0.30.0

2 files

0.29.0

2 files

This release

0.28.1 This release

2 files

0.28.0

2 files

0.27.0

2 files

0.26.0

2 files

0.25.0

2 files

0.24.1

2 files

0.24.0

2 files

0.23.0

2 files

0.22.0

2 files

0.21.0

2 files

0.20.0

2 files

0.19.0

2 files

0.18.0

2 files

0.17.1

2 files

0.17.0

2 files

0.16.0

2 files

0.15.0

2 files

0.14.0

2 files

0.13.0

2 files

0.12.0

2 files

0.11.3

2 files

0.11.2

2 files

0.11.1

2 files

0.11.0

2 files

0.10.1

2 files

0.10.0

2 files

0.9.1

2 files

0.9.0

2 files

0.8.0

2 files

0.7.1

2 files

0.7.0

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.1

2 files

0.5.0

2 files

0.4.0

2 files

0.3.0

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page