djangocms-mcp
by maxnoelp2
README.md
# djangocms-mcp
An [MCP](https://modelcontextprotocol.io/) server for **django CMS 5** that runs inside your
Django project. AI agents (Claude Code, Claude Desktop, claude.ai, ChatGPT, ...) can read and
edit pages, plugins and every content app registered in the Django admin, such as
djangocms-stories, without any app-specific code.
Everything an agent does goes through the same forms, permission checks and signals as the
Django admin, and it acts as a real Django user. With djangocms-versioning it only ever
changes drafts; publishing is off by default.
## Features
- **26 tools**: discovery (site info, content types, plugin types with JSON schemas), pages
(tree, create, translate, update, move), plugins (add, update, move, delete, nested
plugins), generic content (list, get, create, update, delete for any admin-registered
model), versions (list, create draft, publish, unpublish, discard draft).
- **Automatic discovery**: whatever is registered in the Django admin is reachable,
minus a fixed block list and your include/exclude/read-only settings.
- **Admin semantics**: validation and saving through the `ModelAdmin` and plugin forms
(for example HTML sanitizing in djangocms-text), admin log entries, CMS signals.
- **Optional versioning**: works with and without djangocms-versioning.
- **Two transports**: stdio (`manage.py mcp_stdio`) for local clients, stateless
Streamable HTTP at `/mcp` for remote ones. Runs under WSGI and ASGI.
- **Auth**: hashed API tokens per user (optionally read-only), OAuth 2.1 through
django-oauth-toolkit for claude.ai and ChatGPT.
- **Audit log** of every tool call.
Requirements: Python 3.10+, django CMS 5.x, Django 5.2 or 6.0 (the tested versions).
## Quickstart
```bash
pip install djangocms-mcp # or "djangocms-mcp[oauth]" for OAuth
```
```python
# settings.py
INSTALLED_APPS = [
# ... django CMS apps
"djangocms_mcp",
]
# urls.py: before the django CMS URLs
urlpatterns = [
path("admin/", admin.site.urls),
path("", include("djangocms_mcp.urls")), # serves /mcp
# ...
]
```
```bash
python manage.py migrate
```
Create a dedicated Django user for the agent (a staff user with the permissions it needs,
not a superuser). See [docs/installation.md](docs/installation.md) for details.
### Local: stdio
The client starts `manage.py mcp_stdio` itself. The agent acts as `--user`.
Claude Code:
```bash
claude mcp add djangocms -- /path/to/venv/bin/python /path/to/project/manage.py mcp_stdio --user agent
```
Claude Desktop (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"djangocms": {
"command": "/path/to/venv/bin/python",
"args": ["/path/to/project/manage.py", "mcp_stdio", "--user", "agent"]
}
}
}
```
### Remote: HTTP with an API token
```bash
python manage.py mcp_token create --user agent --name "Claude Code"
```
The token (`dcm_…`) is printed once. Then:
```bash
claude mcp add --transport http djangocms https://cms.example.com/mcp \
--header "Authorization: Bearer dcm_..."
```
### claude.ai and ChatGPT: OAuth
The hosted apps connect with OAuth 2.1. Install `djangocms-mcp[oauth]`, configure
django-oauth-toolkit as described in [docs/security.md](docs/security.md), then add
`https://cms.example.com/mcp` as a custom connector.
More clients (MCP Inspector, ChatGPT, Claude Desktop with a remote server):
[docs/clients.md](docs/clients.md).
## Settings
All settings live in one dict, `DJANGOCMS_MCP`; see
[docs/configuration.md](docs/configuration.md) for every key.
```python
DJANGOCMS_MCP = {
"ALLOW_PUBLISH": False, # publish/unpublish tools
"ALLOW_DELETE": False, # delete_object for plain models
"EXCLUDE_MODELS": ["myapp.*"],
"READ_ONLY_MODELS": ["filer.file", "filer.image", "filer.folder"],
"RESOURCE_URL": "https://cms.example.com/mcp", # canonical endpoint URL (OAuth)
}
```
## Safety defaults
- HTTP requires a valid bearer token (`REQUIRE_AUTH = True`); invalid tokens are always
rejected. The endpoint ignores session cookies.
- The agent can never do more than its Django user can do in the admin.
- With djangocms-versioning only drafts are changed; `publish`/`unpublish` are disabled
until you set `ALLOW_PUBLISH = True`. `delete_object` needs `ALLOW_DELETE = True`.
- Users, groups, permissions, sessions, tokens, versions and other internals are never
exposed, whatever the settings say.
- Every tool call is logged (`MCPAuditLog`).
- Content from the CMS is data, not instructions: the built-in server instructions tell
the agent so. Read [docs/security.md](docs/security.md) on prompt injection.
## Documentation
- [Installation](docs/installation.md)
- [Configuration](docs/configuration.md)
- [Clients](docs/clients.md)
- [Security and OAuth](docs/security.md)
- [Changelog](CHANGELOG.md)
## Development
```bash
uv sync
uv run pytest
uv run pytest --ds=tests.testproject.settings_noversioning
uv run ruff check . && uv run ruff format --check .
uv run nox # full matrix (Python 3.10/3.13, Django 5.2/6.0, +/- versioning)
tests/smoke/run_smoke.sh # built wheel in a fresh project
```
License: BSD-3-Clause.