django-admin-fastmcp

Django admin을 MCP 서버로 노출하는 재사용 가능한 Django 앱으로, FastMCP 기반으로 구축되었습니다.

모든 도구 호출은 bearer 토큰을 소유한 스태프 사용자로 실행됩니다. 모든 도구 호출은 먼저 ModelAdmin에 권한을 요청합니다. 슈퍼유저는 admin에서 슈퍼유저가 할 수 있는 모든 것을 할 수 있습니다. 스태프 사용자는 해당 스태프 사용자가 admin에서 할 수 있는 것만 정확히 할 수 있으며, 그 이상은 할 수 없습니다.

SPEC.md가 전체 사양입니다.

작동 방식

세 가지 규칙이 패키지를 정의합니다:

1. 병렬 권한 시스템 없음. 권한 부여는 ModelAdmin 메서드에 위임됩니다: has_view_permission, has_add_permission, has_change_permission, has_delete_permission, get_queryset, get_readonly_fields, get_actions. 행을 숨기는 get_queryset 오버라이드는 MCP에서도 행을 숨깁니다.

2. 병렬 데이터 표면 없음. 쓰기는 admin 자체의 ModelForm과 save_model을 통해 이루어진 후 LogEntry를 기록합니다. admin 기록 페이지는 진실을 유지합니다.

3. 실패 시 폐쇄. 해결되지 않은 모든 조회, 누락된 ModelAdmin, 알 수 없는 작업, 알 수 없는 필드, 알 수 없는 도구는 호출을 거부합니다.

설치

uv add django-admin-fastmcp

앱을 설정에 추가합니다:

INSTALLED_APPS = [
    ...,
    "django.contrib.admin",
    "django_admin_fastmcp",
]

ADMIN_FASTMCP = {
    "SERVER_NAME": "acme-admin",
    "EXCLUDE_MODELS": ("auth.Permission", "auth.Group"),
    "WRITABLE_MODELS": (),          # empty means no writes at all
}

OAuth 엔드포인트를 admin과 같은 사이트에 마운트합니다:

# urls.py
urlpatterns = [
    # RFC 8414 fixes this one at the site root.
    path("", include("django_admin_fastmcp.well_known_urls")),
    # This prefix is yours to choose. Match it to the path in MCP_URL.
    path("admin/mcp/", include("django_admin_fastmcp.urls")),
    path("admin/", admin.site.urls),
]

패키지는 접두사를 하드코딩하지 않습니다. 메타데이터 문서가 광고하는 모든 URL은 reverse()에서 비롯되므로, 엔드포인트를 /backoffice/oauth/에 마운트하는 프로젝트는 검색에서 해당 경로를 얻고 클라이언트가 이를 따릅니다. 두 가지 규칙: well-known 문서는 루트에 있어야 합니다. 클라이언트가 발급자(issuer)에서 URL을 파생하기 때문이며, 엔드포인트는 admin과 같은 사이트에 있어야 합니다. 동의 페이지가 admin 세션 쿠키를 사용하기 때문입니다.

마이그레이션을 적용합니다:

python manage.py migrate django_admin_fastmcp

그 외에는 없습니다. 모델별 등록, 믹스인, 데코레이터가 없습니다. 서버는 admin이 이미 노출하는 모든 것을 노출합니다.

클라이언트 연결

서버를 실행하고( 배포 참조), 등록합니다:

# Claude Code
claude mcp add --transport http acme-admin https://<host>/admin/mcp

후행 슬래시가 없는 경로를 사용하세요. /admin/mcp/는 /admin/mcp로 307 리다이렉트를 응답하며, 모든 클라이언트가 POST에서 리다이렉트를 따르는 것은 아닙니다.

토큰도 헤더도 없습니다. 첫 번째 호출이 표준 MCP OAuth 흐름을 시작합니다:

1. 클라이언트가 Django 사이트의 인증 페이지에서 브라우저를 엽니다.

2. admin 세션 쿠키가 사용자를 식별합니다. 로그아웃된 경우 일반 admin 로그인이 먼저 나타납니다.

3. 동의 페이지에 클라이언트 이름과 승인의 의미가 표시됩니다. 승인합니다.

4. 클라이언트가 토큰을 받고 연결합니다. 토큰은 스스로 갱신합니다.

OAuth와 함께 streamable HTTP를 사용하는 모든 MCP 클라이언트는 동일하게 작동합니다(예: Cursor 또는 FastMCP Client).

접근 관련 규칙:

• 모든 스태프 사용자는 자신만을 위해 클라이언트를 인증할 수 있습니다.

• 권한 부여는 자신의 admin 권한으로만 작동하며, 그 이상은 아닙니다. 별도의 권한 시스템은 없습니다: admin에서 모델을 변경할 수 있는 사람은 서버가 해당 모델을 WRITABLE_MODELS에 나열할 때 MCP를 통해서도 변경할 수 있습니다.

• 리프레시 토큰은 REFRESH_TOKEN_TTL_DAYS(기본값 90) 후에 만료되므로 재동의가 그 주기로 발생합니다. 폐기는 권한 부여 변경 목록에서의 admin 작업입니다.

도구

admin 네임스페이스 아래에 마운트된 11개의 일반 도구로, 와이어 이름은 admin_list_models 등입니다. 각각 model을 "app_label.ModelName"으로 받습니다. 도구 목록은 정적입니다. 사용자별로 다른 것은 각 도구가 해당 사용자가 보고 할 수 있는 것입니다.

읽기

쓰기

쓰기 도구는 모델이 WRITABLE_MODELS에 나열되어 있어야 합니다. 나머지는 모델별, 객체별로 사용자의 admin 권한이 결정합니다. 목록에 없는 모델은 누가 호출하든 모든 쓰기와 모든 작업을 거부합니다. 민감한 모델(예: 이벤트 로그)은 목록에서 제외하세요. 그러면 어떤 MCP 클라이언트도 해당 모델에 쓸 수 없습니다.

반환된 모든 행은 pk를 문자열로, admin_url을 포함하므로 에이전트가 실제 admin에 대한 링크를 사람에게 전달할 수 있습니다.

설정

모든 키는 ADMIN_FASTMCP 딕셔너리에 있습니다. 알 수 없는 키는 시작 시 오류입니다.

실제 배포에는 SITE_URL과 MCP_URL을 설정하세요. MCP_URL은 일치해야 하는 세 가지의 단일 소스입니다: 엔드포인트가 제공되는 경로, 검색이 광고하는 resource, 모든 토큰이 바인딩되는 대상(audience). 경로 기본값은 /admin/mcp입니다. 시작 검사는 경로가 없는 MCP_URL을 거부합니다. 전체 오리진이 보호된 리소스로 광고될 수 있기 때문입니다.

ModelAdmin별 노브

ModelAdmin 클래스에 설정합니다. 믹스인은 필요 없습니다:

class InvoiceAdmin(admin.ModelAdmin):
    mcp_expose = False                     # hide this model from MCP entirely
    mcp_fields = ("number", "total")       # allowlist of serialized fields
    mcp_exclude_fields = ("internal_note",)  # denylist of serialized fields

REDACT_FIELDS가 mcp_fields보다 우선합니다. 비밀번호 필드를 명시적으로 나열해도 공개되지 않습니다.

안전

슈퍼유저용 admin MCP 서버는 언어 모델이 구동하는 프로덕션 데이터베이스에 대한 원격 셸입니다. 안전장치:

• WRITABLE_MODELS는 기본적으로 비어 있으므로 배포가 이름을 지정할 때까지 어떤 모델도 쓰기를 허용하지 않습니다. 그 외에는 모든 호출에서 ModelAdmin을 통해 요청되는 일반적인 Django 권한입니다.

• 액세스 토큰은 수명이 짧습니다. 솔티드 해시만 저장되므로 유출된 데이터베이스 행을 재생할 수 없습니다.

• delete_object와 run_action은 기본적으로 미리보기이며 confirm=True가 될 때까지 아무것도 변경하지 않습니다.

• 모든 변경은 권한의 사용자에게 귀속된 LogEntry를 기록하며, 변경 메시지에 클라이언트 이름이 포함됩니다(예: "Changed status. Via MCP (client: Claude Code)."). LogEntry를 기록할 수 없는 쓰기는 롤백됩니다.

• 패키지 자체 모델, sessions.Session, authtoken.Token은 설정과 관계없이 절대 노출되지 않습니다.

• auth.Permission과 auth.Group을 WRITABLE_MODELS에 두지 마세요. 권한을 부여할 수 있는 에이전트는 권한 모델을 벗어날 수 있습니다.

배포

별도 프로세스. Django 프로젝트 옆에 MCP 서버를 실행합니다:

python manage.py admin_mcp_serve

MCP_URL의 경로(기본값 /admin/mcp)를 MCP_URL의 포트에서 제공하며, URL에 포트가 없으면 8765에서 제공합니다. 둘 다 --host와 --port로 재정의할 수 있습니다. 기존 서빙 구성은 변경되지 않습니다. /admin/mcp를 인그레스를 통해 해당 포트로 라우팅하고 Authorization 헤더가 통과하는지 확인하세요.

마운트(M3). 프로젝트의 asgi.py 내부의 /admin/mcp에 서버를 마운트합니다. 한 가지 제약: 정확한 경로에 대한 디스패치. OAuth 엔드포인트는 동일한 접두사 바로 아래(/admin/mcp/authorize 등)에 있으며 Django가 계속 서빙해야 하므로 /admin/mcp 아래의 모든 것을 FastMCP로 보내는 디스패처는 이를 삼켜버릴 수 있습니다. 레시피는 마일스톤 M3와 함께 제공됩니다.

서버는 상태 비저장이므로 로드 밸런서 뒤의 모든 인스턴스가 모든 요청을 처리할 수 있습니다.

개발

make install     # bootstrap uv, pin Python, install dependencies
make test        # run the permission matrix
make check       # format, lint, typecheck, and test
make migrate     # migrate the test project
make serve       # run the MCP server against the test project on :8765/admin/mcp
make help        # everything else

라이선스

MIT