skycloak-mcp

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

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

빠른 시작

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

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

그런 다음 다음과 같은 요청을 해보세요.

• "내 Keycloak 클러스터 중 업그레이드가 지연된 것은 무엇인가요?"

• "EU 클러스터에 Google 및 GitHub 로그인이 있는 스테이징 영역을 만드세요."

• "지난 주에 프로덕션 영역에 누가 추가되었나요?"

• "관리자 이벤트를 Datadog 웹훅으로 전달하는 SIEM 대상을 설정하세요."

Related MCP server: MCP Authentik

인증 및 보안

• Hosted HTTP, OAuth 사용 (구성할 자격 증명 없음). 클라이언트를 헤더 없이 https://mcp.skycloak.io로 지정하세요. 서버는 401 응답과 함께 /.well-known/oauth-protected-resource에 있는 RFC 9728 메타데이터에 대한 포인터를 반환합니다. 클라이언트는 Skycloak 로그인 영역에 대해 브라우저 인가 코드 흐름을 실행하고, 그 결과로 받은 액세스 토큰은 세션이 실행되는 짧은 수명의 워크스페이스 범위 API 키로 교환됩니다. 키는 한 시간 동안 지속되며 자동으로 갱신됩니다. 클라이언트 구성에 저장되는 것은 없습니다.

• Hosted 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은 저장된 키를 제거합니다.

• Headless / 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을 반환합니다.

• 파괴적 도구는 확인이 필요합니다: 예를 들어, 영역을 삭제하려면 명시적인 confirm=true 인수가 필요합니다.

• 요청은 Skycloak 요금제에 따라 속도 제한이 적용됩니다. 429 응답 시 서버는 Retry-After를 표시합니다.

도구

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

도구 이름은 skycloak_ 접두사를 가지며 아래 표에서는 생략됩니다. 따라서 list_clusters는 클라이언트에서 skycloak_list_clusters입니다.

규칙: 파괴적 도구(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가 필요합니다.

연결

호스팅된 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 /healthz 및 GET /readyz는 인증되지 않으며 프로세스가 실행 중임만 보고합니다. 의도적으로 Skycloak API를 조사하지 않으므로 업스트림 장애가 모든 복제본의 프로브를 동시에 실패시키지 않습니다. 서버는 세션 상태를 보유하지 않으므로 복제본에 세션 선호도가 필요하지 않으며 자유롭게 확장 또는 롤링할 수 있습니다. SIGTERM은 새 연결을 중지하고 진행 중인 호출을 드레인합니다.

OAuth 경로는 SKYCLOAK_ISSUER와 SKYCLOAK_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 email이 scopes_supported로 나열되어 있으며, WWW-Authenticate 챌린지는 이를 scope 매개변수로 반복하므로 둘 중 하나를 읽는 클라이언트는 영역에 이를 요청합니다. openid는 필수입니다. 토큰 교환 시 대시보드가 Keycloak의 userinfo 엔드포인트를 호출하고 Keycloak이 openid 없이 부여된 토큰을 거부하기 때문입니다. openid 없이 도착한 토큰은 성공할 수 없는 교환으로 전달되지 않고 검증 시 401과 챌린지와 함께 거부되므로, 이전에 부여를 보유한 클라이언트는 재시도를 중단하고 다시 로그인합니다. 발급자 또는 대시보드 변수 중 하나를 비우면 OAuth가 완전히 꺼지고 서버는 API 키에 대한 챌린지로 돌아갑니다.

시작 시 해결된 연결 구성(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 키는 절대 기록되지 않습니다.

구성

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

개발

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를 참조하세요.