django-openapi-mcp

This repository is an educational example designed to demonstrate how you can seamlessly bridge Django, Django REST Framework, and the Model Context Protocol (MCP). Feel free to clone, explore, and adapt this code into your own projects!

By leveraging OpenAPI in your Django projects, your API's specification is already complete. We automatically transform existing documentation into ready-to-use AI tools, eliminating the need for hand-written glue code entirely.

If you want an AI assistant (Claude and friends) to operate your Django app, fetch a record, run a filtered query, take an action etc. They need "tools" (i.e. machine-readable descriptions of what your API does). The usual way is to hand-write one for every endpoint, then maintain them forever as the API changes.

This reference project demonstrates how to skip that. This framework reads the OpenAPI schema already generated by drf-spectacular for your Django REST Framework project and automatically exposes each endpoint as a Model Context Protocol (MCP) tool. Your schema is the single source of truth: change the API, and the tools update instanly.

It's built on the official mcp Python SDK, so it speaks the real protocol over stdio (Claude Desktop / Claude Code) and Streamable HTTP (production).

  DRF views ──drf-spectacular──▶ OpenAPI schema ──▶ MCP tools ──▶  Any MCP client (stdio + Streamable HTTP)

---

Features

• Your schema is the single source of truth. Each operationId becomes a tool name, parameters become the tool's inputs, descriptions carry through. Just define an endpoint once.
• Safe by default. Only read-only GET endpoints become tools. Write operations (POST/PUT/PATCH/DELETE) are strictly opt-in. Nothing that can change or delete data is exposed to an AI unless you say so.
• Authentication included. Real Django APIs are locked down, so the generated tools carry credentials (DRF token, bearer/JWT, or a custom header) through to your endpoints. Auth applies to every call.
• Zero config to start. If drf-spectacular already works in your project, so does this.
• Not tied to any one AI. Built on the official SDK over stdio and Streamable HTTP. Anything that speaks MCP (Claude Desktop, Claude Code, your own agent loop) can call the tools. No model or vendor lock-in.

---

Exploring the Framework

Because this is a reference framework to be adapted into your own projects, the best way to understand it is to clone the repository and run the bundled demo.

git clone https://github.com/Shanahan-Suresh/django-openapi-mcp
cd django-openapi-mcp

Setup

To see how this pattern is integrated, look at the provided example project. It relies on DRF and drf-spectacular. If you adapt this source code for your own project, the wiring requires adding the app and one settings block:

# settings.py
INSTALLED_APPS = [
    # ...
    "rest_framework",
    "drf_spectacular",
    "django_openapi_mcp",  # (assuming you copied this folder from the repo into your project)
]

REST_FRAMEWORK = {
    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
}

DJANGO_OPENAPI_MCP = {
    "BASE_URL": "http://127.0.0.1:8000",   # where generated tools send requests
}

That's the whole setup. Now run the server:

python manage.py run_mcp_server --transport stdio        # for Claude Desktop / Code
python manage.py run_mcp_server --transport http --port 8800   # Streamable HTTP at /mcp

Two things happen in two places. The schema is read in-process by drf-spectacular when the server starts (no extra HTTP round-trip, no self-call). Tool execution hits your live API at BASE_URL. So your API server needs to be running before an AI actually calls a tool, but not just to list them.

Connect a client

Any MCP-compatible client can launch the server and call the generated tools. With Claude Desktop, open Settings → Developer → Edit Config. That opens the correct claude_desktop_config.json for your install. Add:

{
  "mcpServers": {
    "my-django-api": {
      "command": "/path/to/your/.venv/bin/python",
      "args": ["manage.py", "run_mcp_server", "--transport", "stdio"],
      "cwd": "/path/to/your/django/project",
      "env": { "DJANGO_SETTINGS_MODULE": "config.settings" }
    }
  }
}

Restart the client and your endpoints show up as tools. Every other client connects the same way: Claude Code via claude mcp add, a custom agent over stdio, or Streamable HTTP at /mcp for a deployed server.

Want to confirm it works before wiring up any client? The example/ project ships a runnable probe script and works with the MCP Inspector. See example/README.md. For the full Claude Desktop walkthrough, see docs/claude-desktop.md.

Configuration

All keys live under DJANGO_OPENAPI_MCP in settings.py:

Key	Default	Purpose
BASE_URL	http://localhost:8000	Where generated tools send HTTP requests.
INCLUDE_METHODS	["GET"]	HTTP methods to expose. Add write methods to opt in.
EXCLUDE_PATHS	[]	Path prefixes to skip (e.g. ["/api/schema"]).
INCLUDE_PATHS	None	If set, only these path prefixes are exposed.
AUTH	None	Credential passthrough (see below).
SCHEMA_URL	None	Fetch the schema over HTTP instead of generating it in-process.
SERVER_NAME	"django-openapi-mcp"	Name advertised to MCP clients.
TIMEOUT	30	HTTP timeout (seconds).

Authentication

DJANGO_OPENAPI_MCP = {
    "AUTH": {"type": "token", "token": "...", "scheme": "Token"},   # Authorization: Token ...
    # {"type": "bearer", "token": "..."}                            # Authorization: Bearer ...
    # {"type": "header", "name": "X-API-Key", "value": "..."}       # custom header
}

Enabling write operations (opt-in)

Read-only is the default. An AI with DELETE access could a bad day waiting to happen. When you actually want write tools, opt in explicitly:

DJANGO_OPENAPI_MCP = {
    "INCLUDE_METHODS": ["GET", "POST"],   # exposes create endpoints too
}

---

Try the example

The fastest way to see the whole thing work is the runnable demo in example/: a tiny shop API (products + orders, with an in_stock filter). Full walkthrough in example/README.md. The short version:

cd example
python manage.py migrate
python seed.py                       # a few sample products & orders
python manage.py runserver           # terminal 1: the API
python manage.py run_mcp_server      # terminal 2: the MCP server (stdio)

You get four tools (products_list, products_retrieve, orders_list, orders_retrieve), and the in_stock query-param filter shows how a tool argument maps straight through to a query string.

---

How it works

Three steps, and the source is laid out to match them:

1. Introspect: drf_spectacular.generators.SchemaGenerator produces the OpenAPI 3 document in-process.
2. Generate: each operation becomes a tool: operationId → name, summary/description → description, path + query parameters → a JSON Schema ($refs resolved, path params marked required).
3. Serve: the official SDK's low-level Server advertises the tools (list_tools) and runs them (call_tool) by mapping arguments onto an HTTP request to BASE_URL, with auth attached.

The source mirrors that pipeline:

• src/django_openapi_mcp/introspect.py: get the OpenAPI schema in-process via drf-spectacular's SchemaGenerator, with a URL fallback and full $ref resolution.
• src/django_openapi_mcp/tools.py: turn each OpenAPI operation into a tool spec (operationId → name, parameters mapped to JSON Schema, collision handling for duplicate names).
• src/django_openapi_mcp/server.py: build the MCP server on the SDK's low-level Server, wiring list_tools and call_tool to execute requests against the live API at BASE_URL.
• src/django_openapi_mcp/transport.py: serve over stdio (Claude Desktop) and Streamable HTTP (production).
• src/django_openapi_mcp/conf.py / auth.py: config defaults (safe-by-default GET-only) and credential passthrough to every outbound request.

---

Related projects

There are already several great works in this space, and they're well worth checking out:

• django-mcp: A feature-rich Django integration that exposes models, custom views, and even Django Admin actions to Claude.
• django-rest-framework-mcp: A DRF-focused package that transforms existing ViewSets and Serializers into MCP tools.
• openapi-to-mcp, openapi-mcp-generator: OpenAPI → MCP converters.
• FastMCP: includes native OpenAPI support.

License

MIT