Skycloak

공식

Skycloak 관리형 Keycloak을 위한 Model Context Protocol 서버입니다. 모든 MCP 클라이언트에서 클러스터, 영역, 애플리케이션, SSO 및 사용자를 관리할 수 있습니다.

Skycloak MCP(으)로 무엇을 할 수 있나요?

어떤 MCP 클라이언트에서든 Skycloak(관리형 Keycloak) 클러스터, 영역, SSO를 관리하세요.

  • 클러스터 업그레이드 검토 — Keycloak 업그레이드가 지연된 클러스터를 확인하고 list_cluster_upgradesget_cluster_upgrade_path를 통해 업그레이드 경로를 확인하세요.
  • 영역 프로비저닝create_realmcreate_identity_provider를 사용하여 Google 및 GitHub 로그인이 포함된 영역을 생성하세요.
  • SIEM 전달create_siem_destination을 사용하여 관리자 이벤트를 Datadog 웹훅으로 전달하는 SIEM 대상을 설정하세요.
  • 사용자 정의 도메인 설정create_domainverify_domain을 사용하여 사용자 정의 도메인을 추가하고, DNS 레코드를 가져오고, 확인하세요.

문서

skycloak-mcp

Smithery

Skycloak(관리형 Keycloak)용 공식 Model Context Protocol 서버: 모든 MCP 클라이언트(Claude Desktop, Claude Code, Cursor)에서 클러스터, realm, 애플리케이션, SSO를 관리하세요.

상태: 초기 릴리스. 도구 범위가 계속 확장 중입니다. 사용 가능한 항목은 변경 로그를 참조하세요.

빠른 시작

claude mcp add --transport http skycloak https://mcp.skycloak.io

API 키도, 클라이언트 ID도, 구성도 필요 없습니다. 브라우저가 열리면 Skycloak에 로그인하고 도구가 나타납니다. streamable HTTP를 지원하는 모든 MCP 클라이언트는 동일하게 작동합니다. URL만 제공하면 됩니다.

그런 다음 원하는 것을 요청하세요:

  • "내 Keycloak 클러스터 중 업그레이드가 지연된 것은 무엇인가요?"
  • "EU 클러스터에 Google 및 GitHub 로그인이 포함된 스테이징 realm을 만들어 주세요."
  • "지난주에 프로덕션 realm에 추가된 사람은 누구인가요?"
  • "관리자 이벤트를 Datadog 웹훅으로 전달하는 SIEM 대상을 설정해 주세요."

인증 및 보안

  • 호스팅 HTTP, OAuth 사용(구성할 자격 증명 없음). 헤더 없이 클라이언트를 https://mcp.skycloak.io에 연결하세요. 서버는 401로 응답하며 /.well-known/oauth-protected-resource에 있는 RFC 9728 메타데이터를 가리킵니다. 클라이언트는 Skycloak 로그인 realm에 대해 브라우저 인증 코드 흐름을 실행하고, 받은 액세스 토큰은 세션이 사용하는 단기 워크스페이스 범위 API 키로 교환됩니다. 키는 1시간 동안 유효하며 자동으로 갱신됩니다. 클라이언트 구성에는 아무것도 저장되지 않습니다.
  • 호스팅 HTTP, API 키 사용. Skycloak 대시보드에서 키를 만들고 Authorization: Bearer <key>(또는 API-Key: <key>)로 보내세요. 모든 요청은 자체 자격 증명을 지니며 해당 자격 증명의 워크스페이스로만 작동합니다. 서버는 세션 상태를 유지하지 않으므로 요청이 다른 호출자의 상태를 상속하지 않습니다. 키는 사용 전에 검증되지 않습니다. Skycloak API가 권한의 원천이므로 잘못된 키는 연결 시점이 아니라 첫 도구 호출 시 401로 표시됩니다.
  • 도구는 역할에 맞게 제공됩니다. OAuth에서는 세션의 범위가 허용하는 도구만 목록에 표시되므로 읽기 전용 워크스페이스 구성원에게는 403로 응답할 쓰기 도구가 표시되지 않습니다. API 키를 사용하면 전체 도구 표면이 등록되는데, 키의 범위는 서버에 보이지 않기 때문이며, 권한 없는 호출은 API에서 403으로 표시됩니다.
  • 로컬 stdio. skycloak-mcp init를 실행하고 브라우저에서 승인하세요(OAuth 2.0 기기 인증 흐름). 워크스페이스 범위 API 키를 생성하여 운영 체제 키체인에 저장하고 기본 워크스페이스를 자동으로 감지합니다(다른 워크스페이스를 선택하려면 --workspace <id>를 전달). skycloak-mcp logout은 저장된 키를 제거합니다.
  • 헤드리스 / CI. SKYCLOAK_API_KEY 환경 변수를 설정하면(Skycloak 대시보드에서 키 생성) 브라우저를 완전히 건너뜁니다. 이 변수는 항상 키체인보다 우선합니다.
  • 쓰기 작업은 플래그가 아닌 자격 증명으로 제어됩니다. https://mcp.skycloak.io의 호스팅 서버는 쓰기 가능 상태로 실행되며, 실제로 변경할 수 있는 범위는 키의 범위와 워크스페이스 역할에 따라 제한됩니다. 읽기 전용 구성원은 도구 목록과 관계없이 아무것도 변경할 수 없습니다. URL에 ?readonly=true를 추가하면 세션에 읽기 전용 도구 표면이 강제됩니다. 로컬 바이너리는 반대 방식으로, --allow-writes으로 시작하지 않는 한 쓰기 도구를 등록하지 않습니다.
  • 클러스터 자격 증명은 옵트인 방식입니다. get_cluster_credentials은 클러스터의 Keycloak 관리자 자격 증명을 반환하며, 키를 보유한 어시스턴트가 이를 볼 수 있으므로 init는 기본적으로 해당 범위를 요청하지 않습니다. 해당 범위를 지닌 키를 사용하세요. 대시보드에서 만들거나 stdio에서 skycloak-mcp init --allow-credentials으로 로그인하면 됩니다. 범위가 없으면 도구는 두 경로를 모두 설명하는 403을 반환합니다.
  • 파괴적 도구는 확인이 필요합니다. 예를 들어 realm을 삭제하려면 명시적인 confirm=true 인수가 필요합니다.
  • 요청은 Skycloak 요금제에 따라 속도 제한이 적용됩니다. 429 응답이 발생하면 서버는 Retry-After을 표시합니다.

도구

도구 129개: 읽기 전용 58개, 쓰기 71개. 읽기 전용 도구는 항상 사용할 수 있습니다. 호스팅 서버에서는 쓰기 도구도 등록되며 자격 증명의 범위로 제어됩니다. 로컬 바이너리는 --allow-writes으로 시작할 때만 등록합니다.

도구 이름에는 아래 표에서 생략된 skycloak_ 접두사가 붙으므로, list_clusters는 클라이언트에서 skycloak_list_clusters입니다.

영역읽기 전용쓰기 (--allow-writes)
클러스터list_clusters, get_cluster, list_cluster_locations, list_cluster_types, list_cluster_features, list_cluster_versions, list_cluster_upgrades, get_cluster_upgrade_path, get_cluster_credentials, get_cluster_insights, get_cluster_maintenance_windowcreate_cluster, update_cluster, delete_cluster, cancel_cluster_upgrade, set_cluster_maintenance_window, delete_cluster_maintenance_window
엣지 보안get_cluster_security, list_cluster_captcha_domainsupdate_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain
Realmlist_realms, get_realmcreate_realm, update_realm, delete_realm
애플리케이션list_applications, get_application, list_application_roles, list_application_sessionscreate_application, update_application, delete_application, assign_application_role, remove_application_role, rotate_application_secret
ID 공급자list_identity_providers, get_identity_provider, list_identity_provider_templates, discover_oidccreate_identity_provider (OIDC), update_identity_provider, delete_identity_provider, test_identity_provider
사용자, 역할 및 그룹list_realm_users, get_realm_user, list_realm_roles, get_realm_role, list_realm_groups, get_realm_group, list_realm_group_members, list_user_roles, list_user_groupscreate_realm_user, update_realm_user, delete_realm_user, create_realm_role, update_realm_role, delete_realm_role, create_realm_group, update_realm_group, delete_realm_group, assign_realm_user_role, remove_realm_user_role, add_realm_user_to_group, remove_realm_user_from_group
사용자 지정 도메인list_domains, get_domain, list_domain_routes, get_domain_routecreate_domain, verify_domain, delete_domain, create_domain_route, update_domain_route, delete_domain_route
브랜딩 및 테마list_themes, get_theme, get_theme_assignment, get_client_theme_assignment, get_login_branding, get_email_branding, download_theme_contentset_theme_assignment, set_client_theme_assignment, update_theme, delete_theme, upsert_login_branding, delete_login_branding, upsert_email_branding, delete_email_branding
확장 기능list_extensions, list_cluster_extensionsinstall_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension
SMTPget_smtpupsert_smtp, delete_smtp, test_smtp
내보내기 및 로그list_exports, get_export, get_logs, get_security_logs, query_eventscreate_export, delete_export, export_cluster_events
Realm 가져오기 및 내보내기get_realm_export, get_realm_importcreate_realm_export, create_realm_import, create_realm_import_upload_url
SIEMlist_siem_destinations, get_siem_destinationcreate_siem_destination, update_siem_destination, delete_siem_destination, test_siem_destination
웹훅list_webhook_event_types, list_webhook_subscriptions, get_webhook_subscriptioncreate_webhook_subscription, update_webhook_subscription, delete_webhook_subscription, test_webhook_subscription

규칙: 파괴적 도구(delete_*, uninstall_extension, cancel_cluster_upgrade)는 confirm=true이 필요합니다. create_cluster은 비동기식입니다. 클러스터가 available 상태가 될 때까지 get_cluster을 폴링하세요. create_domain은 고객이 생성해야 하는 DNS 레코드를 반환하고, verify_domain은 DNS 검사를 트리거합니다. set_theme_assignment은 Keycloak 테마 유형별로 사용자 지정 테마를 활성화합니다(빈 문자열은 기본 제공 테마로 재설정). update_cluster_security은 CAPTCHA 설정을 건드리지 않습니다. Realm 가져오기/내보내기는 하나의 realm 구성을 이동하며, 전체 클러스터 데이터베이스를 덤프하는 create_export과는 별개입니다. 둘 다 비동기식이며, realm 아카이브는 항상 암호화되므로 내보내기에 사용한 비밀번호가 다시 가져올 때 필요합니다. realm은 기존 내보내기(source_export_id)에서 직접 가져오거나 업로드된 아카이브(create_realm_import_upload_url, PUT, 그다음 upload_s3_key)에서 가져올 수 있습니다. 가져오기는 realm을 생성하며 덮어쓰지 않고 이름 충돌을 거부합니다. 사용자와 자격 증명을 함께 가져오므로 confirm=true이 필요합니다.

프롬프트

8개의 프롬프트가 도구 표면의 시작점을 제공합니다. 클라이언트는 이를 슬래시 명령 또는 제안된 작업으로 표시합니다. 각 프롬프트는 인수(realm, 클러스터, 시간 범위)를 받아 올바른 순서로 올바른 도구를 모델에 안내합니다.

프롬프트기능
audit_self_registration하나의 클러스터 또는 전체에서 자체 등록을 허용하는 모든 realm 찾기
review_upgradesKeycloak 버전이 뒤처진 클러스터를 찾아 업그레이드 경로 제시
triage_failed_loginsrealm의 최근 실패한 로그인을 가져와 소스 IP별로 그룹화
review_identity_providersrealm의 SSO 연결을 나열하고 특정 연결이 활성화되어 있는지 확인
review_admin_changesrealm에서 최근 누가 무엇을 변경했는지 표시(로그인 및 보안 설정 중심)
provision_environment클러스터 생성, realm 추가, ID 공급자 연결(각 단계 확인)
set_up_custom_domain사용자 지정 도메인 추가, 정확한 DNS 레코드 제공, 검증, realm에 연결
rotate_client_secret영향 범위를 먼저 설명한 후 애플리케이션의 클라이언트 시크릿 재생성

프롬프트는 이름이 지정된 도구와 동일한 방식으로 제어됩니다. 변경을 수행하는 세 가지 프롬프트는 참조하는 쓰기 도구를 호출할 수 있는 세션에만 제공되며, 지침은 모델이 무엇이든 변경하기 전에 사용자에게 확인하도록 안내합니다. 파괴적 도구에 대한 confirm=true 요구 사항도 그 위에 그대로 적용됩니다.

스킬

프롬프트가 시작점이라면 스킬은 모델이 필요 시 로드하는 완전한 운영 플레이북입니다. 서버는 4개의 스킬을 제공하며, 초안 SEP-2640 Skills 확장을 통해 제공됩니다. 기능에 io.modelcontextprotocol/skills을 선언하고, skills/listskills/get에 응답하며, 각 SKILL.mdskill://<name>/SKILL.md의 일반 리소스로 제공하고 목록 항목에 sha256 다이제스트를 포함합니다. OpenAI의 플러그인 디렉터리는 정확히 이 형태로 스킬을 가져옵니다.

스킬내용
auth-incident-triage"사용자가 로그인할 수 없음" 문제 분류: 이벤트, WAF 로그, 클러스터 상태를 사용하여 플랫폼 장애, 공격, 구성 변경을 구분합니다. 읽기 전용
enterprise-sso-rollout엔터프라이즈 IdP를 realm에 종단 간 연결: 발급자 검증, 업스트림 앱 등록, 브로커 구성, 연결 테스트, 실제 로그인 이벤트에 대한 검증
keycloak-migration-doctorKeycloak 내보내기, 가져오기 또는 마이그레이션을 지원팀이 실제로 보는 차단 요소(스크립트 정책, 레거시 /auth 경로, 부분 내보내기 기대치)에 대해 사전 점검하고, 일반 대시보드 알림 대신 실제 error_message을 읽어 실패한 작업을 진단
keycloak-upgrade-readiness버전 차이를 평가하고, 새 Keycloak 버전이 깨뜨리는 것(확장 기능, 테마)을 파악하며, 내보내기를 롤백 계획으로 삼아 환경 전반의 배포 순서를 설계

스킬은 이름이 지정된 도구와 동일한 제어를 따릅니다. 쓰기 도구를 중심으로 구축된 세 가지 워크플로는 읽기 전용 세션에 제공되지 않으며, 범위가 제한된 세션에는 실제로 보유한 도구의 스킬만 제공됩니다. 소스는 internal/tools/skills/에 있으며 스킬별로 하나의 디렉터리로 구성되고 표준 Agent Skills 형식을 따르므로 로컬 스킬 디렉터리에 그대로 복사해도 작동합니다.

연결

호스팅 HTTP의 가장 간단한 방법은 OAuth이며 자격 증명이 전혀 필요 없습니다:

claude mcp add --transport http skycloak https://mcp.skycloak.io

첫 호출에서 브라우저가 열리고 Skycloak 로그인 페이지에서 승인하면 도구가 나타납니다. 둘 이상의 워크스페이스에 속한 경우 원하는 워크스페이스를 지정하세요:

claude mcp add --transport http skycloak "https://mcp.skycloak.io?workspace=<workspace-id>"

그렇지 않으면 Skycloak 대시보드에서 API 키를 만들고 MCP 클라이언트가 이를 bearer 토큰으로 보내도록 구성하세요:

claude mcp add --transport http skycloak https://mcp.skycloak.io --header "Authorization: Bearer sk_sc_XXX"

이렇게 하면 .claude.json에 다음이 추가됩니다:

{
  "mcpServers": {
    "skycloak": {
      "type": "http",
      "url": "https://mcp.skycloak.io",
      "headers": {
        "Authorization": "Bearer sk_sc_XXX"
      }
    }
  }
}

로컬 stdio의 경우 한 번 로그인한 다음 클라이언트를 skycloak-mcp run에 연결하세요:

skycloak-mcp init        # one-time browser sign-in; stores a key in your keychain

Claude Desktop / Cursor (로컬, stdio):

{
  "mcpServers": {
    "skycloak": {
      "command": "skycloak-mcp",
      "args": ["run", "--transport", "stdio"]
    }
  }
}

Claude Code:

claude mcp add skycloak -- skycloak-mcp run --transport stdio

헤드리스/CI(브라우저 없음) 환경에서는 init을 건너뛰고 키를 대신 전달하세요: "env": { "SKYCLOAK_API_KEY": "sk_sc_..." }을 구성에 추가하거나 claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio을 사용하세요.

변경을 의도할 때만 --allow-writes을 추가하세요(skycloak-mcp init --allow-writes로 로그인하거나 쓰기 범위 키를 사용).

호스팅된 HTTP URL에 ?readonly=true을 추가하면 해당 HTTP 세션에 읽기 전용 도구만 노출되고, ?readonly=false을 추가하면 쓰기 가능한 도구 표면을 요청합니다. 쿼리 매개변수는 기본적으로 false이지만, 쓰기 도구는 서버가 --allow-writes으로 시작된 경우에만 등록됩니다.

?workspace=<uuid>을 추가하여 OAuth 세션이 작동할 작업 공간을 선택하세요. 둘 이상에 속한 경우에만 필요합니다. 단일 작업 공간에서는 서버가 자동으로 선택하며, 여러 개에 속하면서 아무것도 지정하지 않으면 연결이 실패하고 목록이 포함된 메시지가 표시됩니다.

HTTP 전송 실행

skycloak-mcp run --transport http --http-addr :8080

자체 자격 증명이 필요 없습니다: 호출자가 요청별로 자격 증명을 제공하므로 배포 시 주입되는 것이 없습니다. GET /healthzGET /readyz은 인증되지 않으며 프로세스가 실행 중인지만 보고합니다. 의도적으로 Skycloak API를 프로브하지 않으므로 상류 장애가 모든 복제본의 프로브를 동시에 실패시키지 않습니다. 서버는 세션 상태를 보유하지 않으므로 복제본에 세션 선호도가 필요 없으며 자유롭게 확장하거나 롤링할 수 있습니다. SIGTERM은 새 연결을 중지하고 진행 중인 호출을 드레인합니다.

OAuth 경로는 SKYCLOAK_ISSUERSKYCLOAK_DASHBOARD_URL이 설정되어 있을 때마다 활성화되며, 기본적으로 설정되어 있습니다. 그러면 GET /.well-known/oauth-protected-resource이 인증되지 않은 상태로 제공되며 영역을 권한 부여 서버로 명명합니다. 해당 resource 값은 SKYCLOAK_PUBLIC_URL이 설정된 경우 그 값에서 가져오고, 그렇지 않으면 요청 자체의 Host과 스킴에서 가져오므로 인그레스 뒤의 단일 호스트 배포에는 추가 구성이 필요 없습니다. 스킴은 X-Forwarded-Proto이 있는 경우 그 값에서 가져오고, 그렇지 않으면 루프백 호스트가 아닌 경우 기본적으로 https으로 설정됩니다. TLS가 상류에서 종료되고 http:// 식별자를 게시하면 클라이언트가 연결한 URL과 일치하지 않기 때문입니다. 인그레스가 Host을 다시 작성하는 경우 SKYCLOAK_PUBLIC_URL을 설정하세요. 문서에는 openid profile emailscopes_supported으로도 나열되며, WWW-Authenticate 챌린지는 이를 scope 매개변수로 반복하므로 둘 중 하나를 읽는 클라이언트는 영역에 이를 요청합니다: openid이 필요합니다. 토큰 교환으로 대시보드가 Keycloak의 userinfo 엔드포인트를 호출하고 Keycloak은 이 없이 부여된 토큰을 거부하기 때문입니다. 이 없이 도착한 토큰은 교환으로 전달되지 않고 401 및 챌린지와 함께 검증 시 거부되므로, 이전에 부여된 권한을 보유한 클라이언트는 재시도를 중단하고 다시 로그인합니다. 발급자 또는 대시보드 변수 중 하나를 비우면 OAuth가 완전히 꺼지고 서버는 API 키에 대한 챌린지로 돌아갑니다.

OPENAI_APPS_CHALLENGE_TOKEN/.well-known/openai-apps-challenge에서 OpenAI의 플러그인 디렉터리 도메인 검증 토큰을 일반 텍스트로만 제공합니다. 설정하지 않으면 경로가 등록되지 않고 404를 반환합니다.

시작 시 해결된 배선을 한 줄로 기록하므로(oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=) 잘못 구성된 배포를 재배포 없이 발견할 수 있습니다. OAuth 경로에서 거부된 모든 요청은 실패한 단계(verify, exchange 또는 scopes), 호출자가 받은 상태 및 기본 오류를 명명하는 한 줄을 기록합니다. 검증 실패는 토큰을 거부한 검사를 추가하고(expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope 등), 교환 실패는 대시보드의 상태와 호출된 호스트를 추가합니다. 호출자는 토큰이 검증되면 토큰의 주체로 나타나며 자격 증명으로는 절대 나타나지 않습니다: 액세스 토큰, Authorization 헤더 및 발급된 API 키는 절대 기록되지 않습니다.

구성

환경 변수기본값
SKYCLOAK_API_KEY없음(stdio에는 선택 사항, HTTP 클라이언트는 API-Key 헤더 제공)
SKYCLOAK_ENDPOINThttps://api.skycloak.io
SKYCLOAK_API_VERSION현재 API 버전
SKYCLOAK_ISSUERhttps://login.app.skycloak.io/realms/skycloak (CLI 로그인 및 HTTP 전송이 토큰을 검증하는 권한 부여 서버)
SKYCLOAK_CLIENT_IDskycloak-mcp (CLI 디바이스 흐름 전용)
SKYCLOAK_DASHBOARD_URLhttps://app.skycloak.io (CLI 키 및 HTTP 세션 키 발급)
SKYCLOAK_PUBLIC_URL없음(각 요청에서 파생, 인그레스가 Host을 다시 작성할 때 설정)
OPENAI_APPS_CHALLENGE_TOKEN/.well-known/openai-apps-challenge에서 OpenAI의 플러그인 디렉터리 검증 토큰 제공. 설정하지 않으면 해당 경로는 404.

명령: init (브라우저 로그인), run (서브), logout (저장된 키 제거). init--workspace <id>, --allow-writes, --allow-credentials, --ttl-days (기본 90)을 허용합니다.

플래그기본값설명
--transportstdiostdio 또는 http
--http-addr:8080HTTP 전송 수신 주소
--allow-writesfalsestdio에 대한 변경 도구 활성화 및 readonly=false이 있는 HTTP 세션이 쓰기 도구를 등록하도록 허용

개발

make build      # build the server binary
make test       # unit tests
make run        # run on stdio for local testing
make inspector  # MCP Inspector against the local binary
make lint       # golangci-lint
make generate   # regenerate the API client from the OpenAPI spec

internal/apiclient 아래의 API 클라이언트는 oapi-codegen으로 Skycloak OpenAPI 사양에서 생성됩니다.

API와 동기화 유지

internal/apiclient의 클라이언트는 oapi-codegen으로 internal/apiclient/openapi.yaml에서 생성됩니다. make generate을 실행하여 새로 고치세요. 커밋된 생성 코드가 사양에서 벗어나면 CI가 실패합니다. 요청은 429/5xx에서 Retry-After 인식 백오프로 재시도됩니다.

배포

각 태그에서 GitHub 바이너리와 ghcr.io/sky-cloak/skycloak-mcp 컨테이너 이미지로 릴리스되며, MCP 레지스트리io.skycloak/skycloak-mcp으로 게시됩니다. 대부분의 사용자는 둘 다 필요하지 않습니다: 호스팅 서버는 설치가 필요 없습니다.

보안

취약점은 비공개로 신고해 주세요. SECURITY.md를 참조하세요.

기여자

Skycloak에서 Guilliano Molaire, Neville Omangi 및 Aphilas가 구축했습니다. 저장소 기록은 공개될 때 스쿼시되었으므로 커밋 로그가 누가 무엇을 작성했는지 반영하지 않습니다.

라이선스

Apache-2.0. internal/apiclient/openapi.yaml의 OpenAPI 설명은 Skycloak 플랫폼 API에서 생성되었으며 (c) Skycloak입니다. 클라이언트를 생성하고 검증할 수 있도록 여기에 포함되었습니다. NOTICE를 참조하세요.