django-mcp-server

Implements the Model Context Protocol specification as a Django extension, translating between standardized MCP protocol messages (tools, resources, prompts) and Django application functionality. Uses a layered architecture with transport abstraction (HTTP/STDIO), session management, and a metaclass-based tool registry that auto-discovers and registers tools during application startup. Enables any MCP-compatible client (Claude AI, Google ADK, custom agents) to invoke Django operations through typed tool interfaces.

Provides a metaclass-based tool registration system where developers define tools by subclassing MCPToolset and decorating methods with @mcp_tool. The metaclass automatically discovers decorated methods at class definition time, extracts type hints and docstrings to generate MCP-compatible schemas, and registers tools in a central registry. Tools are exposed to MCP clients with full type information, parameter validation, and automatic serialization of return values.

Provides a Django management command (mcp_inspect) that introspects the MCP server configuration and registered tools during local development. Displays tool schemas, parameters, descriptions, and authentication requirements in human-readable format. Enables developers to test tool invocation locally without connecting an MCP client, simulating tool calls with custom parameters and inspecting results. Supports schema validation and debugging of tool definitions.

Enforces Django permission checks on a per-tool basis, integrating with Django's permission system to restrict tool access based on user roles and permissions. Tools can declare required permissions through configuration or decorators, and the framework validates user permissions before tool execution. Supports both model-level permissions (add, change, delete) and custom permission definitions. Permission checks are enforced at the transport layer (HTTP) and during tool execution, with proper error responses for unauthorized access.

Supports running multiple independent MCP server instances within a single Django application, each with its own isolated tool registry and configuration. Enables different MCP servers to expose different tool collections to different client groups (e.g., admin tools vs. user tools). Each server instance maintains separate authentication, permission, and session configuration. Multiple servers can coexist in the same Django application through separate URL routes or STDIO processes.

Automatically generates MCP tools from Django ORM models by subclassing ModelQueryToolset and specifying a model class. The system introspects model fields, relationships, and querysets to generate parameterized query tools (list, filter, get, create, update, delete) with schema validation. Implements a query DSL that translates MCP tool parameters into Django ORM calls, with support for filtering, pagination, ordering, and field selection. Handles serialization of model instances to JSON via Django REST Framework serializers.

Provides decorators and publishing functions that expose existing Django REST Framework views as MCP tools without modifying view code. Introspects DRF view classes to extract serializer schemas, HTTP methods, and permission classes, then generates MCP tool schemas that map to view endpoints. Handles request/response translation between MCP protocol and DRF's request/response objects, including authentication token injection and permission enforcement.

Supports both HTTP and STDIO transports for MCP protocol communication, allowing deployment in different environments without code changes. HTTP transport runs as a Django view (MCPServerStreamableHttpView) integrated into URL routing, supporting both WSGI and ASGI application servers. STDIO transport enables local/containerized deployments where the MCP server communicates via standard input/output streams. Transport abstraction layer handles protocol message serialization, session management, and error handling uniformly across both transports.

Implements session management and authentication enforcement for MCP clients, supporting stateless and stateful interaction contexts. Integrates with Django's authentication system (user models, permissions) and supports multiple authentication classes (token-based, OAuth2, custom). Session context is passed through the request/response lifecycle, enabling permission checks and user-scoped data access. Authentication is enforced at the transport layer (HTTP) or session initialization (STDIO), with per-tool permission validation.

Implements a query DSL that translates MCP tool parameters into Django ORM queries, supporting filtering, ordering, pagination, and field selection. The DSL accepts filter parameters in a standardized format (e.g., field__lookup=value), maps them to Django's ORM query syntax, and executes queries with automatic schema validation. Supports nested field access through foreign key relationships, custom field lookups (exact, icontains, gte, lte), and result pagination with limit/offset. Schema generation from model fields ensures type-safe parameter validation.

Introspects Django ORM models and Django REST Framework serializers to automatically generate MCP-compatible tool schemas with type information, field descriptions, and validation rules. Extracts field types, relationships, validators, and help text from model definitions and serializer metadata, then generates JSON schemas that describe tool parameters and return types. Supports nested schema generation for related models and custom field types through serializer configuration.

Implements a metaclass-based tool registry that auto-discovers and registers tools at class definition time by scanning for decorated methods and subclasses. When a class inheriting from MCPToolset or ModelQueryToolset is defined, the metaclass intercepts class creation, extracts tool definitions from decorated methods or model configuration, and registers them in a central registry. The registry maintains tool metadata (schemas, handlers, permissions) and exposes tools to MCP clients through the discovery protocol. No manual registration required; tools are discovered during Django application startup.

Manages the complete request/response lifecycle for MCP protocol messages, including message parsing, tool invocation, result serialization, and streaming response handling. Implements a pipeline architecture with stages for authentication, permission checking, tool execution, and response formatting. Supports streaming responses for large result sets through HTTP chunked transfer encoding or STDIO stream writing. Handles error cases with proper MCP error response formatting and exception propagation.