Skip to main content
Glama
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.