crudkit

A metadata-driven CRUD framework for Django. Define models; get typed object IDs, soft delete, merge, change logging, an activity feed, saved views, AI-populated fields and a generic REST API — without writing per-model serializers, viewsets or routes.

Core concepts

Every CrudKit model inherits BaseCrudKitModel and declares a 3-letter TYPE_ID. Object IDs are rendered as <TYPE_ID><pk> (e.g. CUS42) across the API and UI.

from django.db import models
from crudkit.models import BaseCrudKitModel

class Customer(BaseCrudKitModel):
    TYPE_ID = "CUS"
    name = models.CharField(max_length=255)

    class CrudKitSettings(BaseCrudKitModel.CrudKitSettings):
        search_fields = ["name"]

Included with every model: created_by/updated_by/created_at/updated_at audit columns, a deleted soft-delete flag (soft_delete()), merge support (delete_and_merge_with()), a change log, an activity feed (FeedItem), external-system sync (ExternalObject), saved views/layouts, and optional AI fields (AISummaryField, AICategoryField, AIBooleanField, AITagsField, AIForeignKeyField) populated asynchronously via Celery and pydantic-ai.

Installation

pip install crudkit[api]          # REST API included
pip install crudkit[assistant]    # + AI assistant sidebar (Channels)
pip install crudkit[mcp]          # + remote MCP server with OAuth (e.g. a Claude connector)

INSTALLED_APPS = [
    ...,
    "rest_framework",
    "crudkit",
    "crudkit_assistant",  # optional
]

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": [
        "crudkit_api.permissions.CrudKitModelPermissions",
    ],
    "DEFAULT_PAGINATION_CLASS": "crudkit_api.pagination.CrudKitPagination",
    "DEFAULT_FILTER_BACKENDS": ["crudkit_api.filters.BasicFilter"],
    "PAGE_SIZE": 50,
}

# urls.py — one include registers a full CRUD API for every TYPE_ID model
urlpatterns = [path("api/v1/", include("crudkit_api.urls"))]

The assistant sidebar talks over a WebSocket at ws/assistant/, next to the realtime ws/changes/ socket; route both in your ASGI application (see examples/demo/demo/asgi.py):

application = ProtocolTypeRouter({
    "http": get_asgi_application(),
    "websocket": URLRouter(
        crudkit_api.routing.websocket_urlpatterns + crudkit_assistant.routing.websocket_urlpatterns
    ),
})

The sidebar sees what the user has on screen — the open record, or the list with its saved view, search, filters, visible and selected rows — and can search and read across record types. It only proposes changes (to any record the user may change); each one waits for Confirm. Conversations are stored per user (AssistantConversation, ASC) and resume after a reload. The SPA only shows the assistant when an AI model is configured (CRUDKIT_AI_MODEL or CRUDKIT_AI_MODEL_FACTORY).

CrudKit requires the standard Django model permissions for every API and assistant operation. Projects that need row-level rules can override CrudKitSettings.get_authorized_queryset(user, queryset, action); action is one of view, add, change, or delete. Model actions require change permission and can be narrowed further with CrudKitSettings.has_action_permission(user, instance, action_name).

Settings

MCP server

crudkit_mcp exposes the models as a remote MCP server (streamable HTTP) with its own OAuth 2.1 authorization server (dynamic client registration, PKCE, rotating refresh tokens), so it can be added as e.g. a Claude connector by URL.

INSTALLED_APPS = [..., "crudkit_mcp"]
LOGIN_URL = "/login/"  # the OAuth consent page needs a session login

urlpatterns = [
    path("api/v1/", include("crudkit_mcp.urls")),       # /api/v1/mcp, /api/v1/oauth/...
    path("", include("crudkit_mcp.well_known_urls")),   # /.well-known/oauth-* (site root)
    ...,
]

The tool set is fixed — records are addressed by TYPE_ID and CK-ID, so the same tools serve any project:

With CRUDKIT_MCP_WRITE_ENABLED and a token granted the write scope, four more: create_record, update_record, run_action and add_note.

Every call is filtered through the token user's model, row and action permissions, so a type the user can't view isn't listed and can't be read. CrudKit's own models and Django's (including User) are never exposed; narrow the rest with CRUDKIT_MCP_MODELS = ["CMP", "PER", ...] or opt a single model out with CrudKitSettings.mcp_exclude = True.

Bundled frontend

The wheel ships the built CrudKit web SPA. To serve it, add the app, the context processor, a config dict, and a catch-all url include (last!):

INSTALLED_APPS = [..., "crudkit_frontend"]

TEMPLATES = [{
    ...,
    "OPTIONS": {"context_processors": [
        ...,
        "crudkit_frontend.context_processors.crudkit_config",
    ]},
}]

CRUDKIT_FRONTEND_CONFIG = {"app_name": "My App"}  # injected into the SPA at runtime
CRUDKIT_FRONTEND_LOGIN_REQUIRED = False  # True → redirect anonymous users to LOGIN_URL

# urls.py — must be the LAST pattern; everything unmatched serves the SPA
urlpatterns = [..., path("", include("crudkit_frontend.urls"))]

Static assets are served by django.contrib.staticfiles (or WhiteNoise et al.) from crudkit_frontend/static/, under whatever STATIC_URL the project uses — nothing assumes the default static/ prefix. Contributors hacking on the SPA itself run the Vite dev server from ../frontend against any CrudKit backend; npm run build there regenerates the bundled assets.

Running the tests

cd backend
uv sync --all-extras
uv run manage.py test crudkit crudkit_api crudkit_assistant crudkit_frontend crudkit_mcp tests

License

MIT