Skycloak

skycloak-mcp

Skycloak (yönetilen Keycloak) için resmi Model Context Protocol sunucusu: kümelerinizi, realm'lerinizi, uygulamalarınızı ve SSO'nuzu herhangi bir MCP istemcisinden (Claude Desktop, Claude Code, Cursor) yönetin.

Durum: erken sürüm. Araç kapsamı büyüyor; nelerin mevcut olduğu için değişiklik günlüğüne bakın.

Hızlı başlangıç

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

API anahtarı yok, istemci kimliği yok, yapılandırma yok. Tarayıcınız açılır, Skycloak'a giriş yaparsınız ve araçlar görünür. Streamable HTTP konuşan herhangi bir MCP istemcisi aynı şekilde çalışır: ona yalnızca URL'yi verin, başka bir şey vermeyin.

Sonra bir şey isteyin:

• "Keycloak kümelerimden hangileri yükseltmelerde geride?"
• "AB kümesinde Google ve GitHub girişi olan bir staging realm oluştur."
• "Geçen hafta production realm'ine kim eklendi?"
• "Yönetici olaylarını Datadog webhook'umuza ileten bir SIEM hedefi kur."

Kimlik doğrulama ve güvenlik

• Barındırılan HTTP, OAuth ile (yapılandırılacak kimlik bilgisi yok). İstemcinizi https://mcp.skycloak.io adresine başlık olmadan yönlendirin. Sunucu, /.well-known/oauth-protected-resource adresindeki RFC 9728 meta verilerine işaret eden 401 ile yanıt verir; istemci, Skycloak giriş realm'ine karşı tarayıcı yetkilendirme kodu akışını çalıştırır ve aldığı erişim token'ı, oturumun üzerinde çalıştığı kısa ömürlü, çalışma alanı kapsamlı bir API anahtarıyla değiştirilir. Anahtar bir saat sürer ve otomatik olarak yenilenir. İstemci yapılandırmanızda hiçbir şey saklanmaz.
• Barındırılan HTTP, API anahtarıyla. Skycloak panosunda bir anahtar oluşturun ve bunu Authorization: Bearer <key> (veya API-Key: <key>) olarak gönderin. Her istek kendi kimlik bilgisini taşır ve yalnızca o kimlik bilgisinin çalışma alanı olarak hareket eder. Sunucu oturum durumu tutmaz, bu nedenle bir istek asla başka bir çağıranın durumunu devralmaz. Anahtarlar kullanımdan önce doğrulanmaz: Skycloak API'si yetkilidir, bu nedenle geçersiz bir anahtar, bağlantı zamanında değil, ilk araç çağrısında 401 olarak yüzeye çıkar.
• Araçlar rolünüzle eşleşir. OAuth üzerinden araç listesi, oturumun kapsamlarının izin verdiği şekilde kırpılır; böylece salt okunur bir çalışma alanı üyesine, 403 ile yanıt verecek yazma araçları gösterilmez. API anahtarıyla tüm yüzey kayıtlıdır, çünkü bir anahtarın kapsamları sunucu tarafından görünmez ve yetkisiz bir çağrı, API'den 403 olarak yüzeye çıkar.
• Yerel stdio. skycloak-mcp init komutunu çalıştırın ve tarayıcınızda onaylayın (OAuth 2.0 cihaz yetkilendirme akışı). Çalışma alanı kapsamlı bir API anahtarı üretir, bunu işletim sistemi anahtarlığınızda saklar ve varsayılan çalışma alanınızı otomatik olarak algılar (başka birini seçmek için --workspace <id> geçirin). skycloak-mcp logout saklanan anahtarı kaldırır.
• Başsız / CI. Tarayıcıyı tamamen atlamak için SKYCLOAK_API_KEY ortam değişkenini ayarlayın (Skycloak panosunda bir anahtar oluşturun). Her zaman anahtarlığa göre önceliklidir.
• Yazmalar, bir bayrakla değil, kimlik bilginizle sınırlandırılır. https://mcp.skycloak.io adresindeki barındırılan sunucu yazma özellikli çalışır ve gerçekte değiştirebilecekleriniz, anahtarınızın kapsamları ve çalışma alanı rolünüzle sınırlıdır: salt okunur bir üye, araç listesi ne derse desin hiçbir şeyi değiştiremez. Bir oturum için salt okunur bir araç yüzeyini zorlamak üzere URL'ye ?readonly=true ekleyin. Yerel ikili dosya tam tersi şekilde çalışır ve --allow-writes ile başlatılmadıkça hiçbir yazma aracı kaydetmez.
• Küme kimlik bilgileri isteğe bağlıdır. get_cluster_credentials, bir kümenin Keycloak yönetici kimlik bilgilerini döndürür; anahtarı elinde tutan bir asistan bunları görür, bu nedenle init varsayılan olarak bu kapsamı istemez. Bunu taşıyan bir anahtar kullanın: panoda bir tane oluşturun veya stdio üzerinden skycloak-mcp init --allow-credentials ile giriş yapın. Bu olmadan araç, her iki yolu da açıklayan bir 403 döndürür.
• Yıkıcı araçlar onay gerektirir: örneğin bir realm'i silmek, açık bir confirm=true bağımsız değişkeni gerektirir.
• İstekler Skycloak planınıza göre hız sınırlamasına tabidir; bir 429 yanıtında sunucu Retry-After yüzeye çıkarır.

Araçlar

129 araç: 58 salt okunur ve 71 yazma. Salt okunur araçlar her zaman kullanılabilir. Barındırılan sunucuda yazma araçları da kayıtlıdır ve kimlik bilginizin kapsamlarıyla sınırlandırılır; yerel ikili dosya bunları yalnızca --allow-writes ile başlatıldığında kaydeder.

Araç adları, aşağıdaki tablonun atladığı bir skycloak_ öneki taşır; bu nedenle list_clusters, istemcinizde skycloak_list_clusters olarak görünür.

Alan	Salt okunur	Yazma (--allow-writes)
Kümeler	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_window	create_cluster, update_cluster, delete_cluster, cancel_cluster_upgrade, set_cluster_maintenance_window, delete_cluster_maintenance_window
Uç güvenliği	get_cluster_security, list_cluster_captcha_domains	update_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain
Realm'ler	list_realms, get_realm	create_realm, update_realm, delete_realm
Uygulamalar	list_applications, get_application, list_application_roles, list_application_sessions	create_application, update_application, delete_application, assign_application_role, remove_application_role, rotate_application_secret
Kimlik sağlayıcıları	list_identity_providers, get_identity_provider, list_identity_provider_templates, discover_oidc	create_identity_provider (OIDC), update_identity_provider, delete_identity_provider, test_identity_provider
Kullanıcılar, roller ve gruplar	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_groups	create_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
Özel alan adları	list_domains, get_domain, list_domain_routes, get_domain_route	create_domain, verify_domain, delete_domain, create_domain_route, update_domain_route, delete_domain_route
Marka ve temalar	list_themes, get_theme, get_theme_assignment, get_client_theme_assignment, get_login_branding, get_email_branding, download_theme_content	set_theme_assignment, set_client_theme_assignment, update_theme, delete_theme, upsert_login_branding, delete_login_branding, upsert_email_branding, delete_email_branding
Uzantılar	list_extensions, list_cluster_extensions	install_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension
SMTP	get_smtp	upsert_smtp, delete_smtp, test_smtp
Dışa aktarmalar ve günlükler	list_exports, get_export, get_logs, get_security_logs, query_events	create_export, delete_export, export_cluster_events
Realm içe ve dışa aktarma	get_realm_export, get_realm_import	create_realm_export, create_realm_import, create_realm_import_upload_url
SIEM	list_siem_destinations, get_siem_destination	create_siem_destination, update_siem_destination, delete_siem_destination, test_siem_destination
Webhook'lar	list_webhook_event_types, list_webhook_subscriptions, get_webhook_subscription	create_webhook_subscription, update_webhook_subscription, delete_webhook_subscription, test_webhook_subscription

Kurallar: yıkıcı araçlar (delete_*, uninstall_extension, cancel_cluster_upgrade) confirm=true gerektirir. create_cluster eşzamansızdır: küme available olana kadar get_cluster yoklayın. create_domain, müşterinin oluşturması gereken DNS kayıtlarını döndürür; verify_domain bir DNS kontrolü tetikler. set_theme_assignment, Keycloak tema türü başına özel bir temayı etkinleştirir (boş dize yerleşik varsayılana sıfırlar). update_cluster_security, CAPTCHA ayarlarına dokunmaz. Realm içe/dışa aktarma, bir realm'in yapılandırmasını taşır ve tüm kümenin veritabanını döken create_export'den ayrıdır: her ikisi de eşzamansızdır ve realm arşivi her zaman şifrelenir, bu nedenle dışa aktarmak için kullanılan parolanın tekrar içe aktarmak için gerekli olması gerekir. Bir realm, mevcut bir dışa aktarmadan doğrudan (source_export_id) veya yüklenmiş bir arşivden (create_realm_import_upload_url, PUT, ardından upload_s3_key) içe aktarılabilir; içe aktarma bir realm oluşturur ve üzerine yazmak yerine bir ad çakışmasını reddeder ve kullanıcıları ve kimlik bilgilerini beraberinde getirdiği için confirm=true gerektirir.

İstemler

Sekiz istem, bu araç yüzeyine bir başlangıç noktası verir. İstemciler bunları eğik çizgi komutları veya önerilen eylemler olarak yüzeye çıkarır; her biri bağımsız değişkenler (realm, küme, zaman penceresi) alır ve modeli doğru sırayla doğru araçlardan geçirir.

İstem	Ne yapar
audit_self_registration	Bir küme genelinde veya tümünde kendi kendine kaydolmaya hâlâ izin veren her realm'i bulun
review_upgrades	Keycloak sürümünde geride kalan kümeleri tespit edin ve yükseltme yolunu ortaya koyun
triage_failed_logins	Bir realm için son başarısız girişleri çekin ve kaynak IP'ye göre gruplayın
review_identity_providers	Bir realm'in SSO bağlantılarını listeleyin ve belirli birinin etkin olup olmadığını kontrol edin
review_admin_changes	Bir realm'de yakın zamanda kimin neyi değiştirdiğini gösterin, oturum açma ve güvenlik ayarlarına odaklanın
provision_environment	Bir küme oluşturun, bir realm ekleyin ve her adımı onaylayarak bir kimlik sağlayıcısı bağlayın
set_up_custom_domain	Özel bir alan adı ekleyin, tam DNS kayıtlarını geri verin, doğrulayın ve bir realm'e yönlendirin
rotate_client_secret	Bir uygulamanın istemci sırrını, önce patlama yarıçapını açıklayarak yeniden oluşturun

İstemler, adlandırdıkları araçlarla aynı şekilde sınırlandırılır: değişiklik yapan üçü, yalnızca başvurdukları yazma araçlarını çağırabilecek oturumlara sunulur ve talimatları, herhangi bir şeyi değiştirmeden önce sizinle onaylamasını söyler. Yıkıcı araçlardaki confirm=true gereksinimi yine de üstüne eklenir.

Beceriler

Bir istem bir başlangıç noktasıyken, bir beceri modelin isteğe bağlı olarak yüklediği tam bir operasyonel oyun kitabıdır. Sunucu, taslak SEP-2640 Beceriler uzantısı üzerinden sunulan dört beceriyle birlikte gelir: yeteneklerinde io.modelcontextprotocol/skills bildirir, skills/list ve skills/get yanıtlar ve her SKILL.md'u skill://<name>/SKILL.md adresinde, liste girişinde sha256 özetiyle sıradan bir kaynak olarak sunar. OpenAI'nin eklenti dizini becerileri tam olarak bu şekilde içe aktarır.

Beceri	Ne kodlar
auth-incident-triage	"Kullanıcılar giriş yapamıyor" triyajı: platform kesintilerini saldırılardan ve yapılandırma değişikliklerinden ayırın; olayları, WAF günlüklerini ve küme sağlığını kullanın. Salt okunur
enterprise-sso-rollout	Kurumsal bir IdP'yi bir realm'e uçtan uca bağlayın: veren doğrulaması, yukarı akış uygulama kaydı, broker yapılandırması, bağlantı testi ve gerçek giriş olaylarına karşı doğrulama
keycloak-migration-doctor	Bir Keycloak dışa aktarma, içe aktarma veya geçişini, desteğin gerçekten gördüğü engellere karşı ön kontrol edin (script politikaları, eski /auth yolu, kısmi dışa aktarma beklentileri) ve genel pano bildirimi yerine gerçek error_message'ini okuyarak başarısız bir işi teşhis edin
keycloak-upgrade-readiness	Sürüm sapmasını değerlendirin, yeni Keycloak sürümünün neyi bozduğunu (uzantılar, temalar) belirleyin ve geri alma planı olarak bir dışa aktarmayla ortamlar arasında dağıtımı sıralayın

Beceriler, adlandırdıkları araçlarla aynı sınırlamayı izler: yazma araçları etrafında oluşturulan üç iş akışı salt okunur oturumlardan alıkonur ve kapsamlı bir oturuma yalnızca gerçekten sahip olduğu araçların becerisi sunulur. Kaynaklar, standart Agent Becerileri biçiminde, beceri başına bir dizin olarak internal/tools/skills/ içinde yaşar; böylece yerel bir beceri dizinine doğrudan kopyalanmış olarak da çalışırlar.

Bağlanma

Barındırılan HTTP için en basit yol, hiç kimlik bilgisi gerektirmeyen OAuth'dur:

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

İlk çağrı tarayıcınızı açar, Skycloak giriş sayfasında onaylarsınız ve araçlar görünür. Birden fazla çalışma alanına aitseniz, istediğinizi adlandırın:

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

Aksi takdirde, Skycloak panosunda bir API anahtarı oluşturun ve MCP istemcinizi bunu bir taşıyıcı belirteç olarak gönderecek şekilde yapılandırın:

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

Bu, .claude.json dosyasına aşağıdakileri ekler:

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

Yerel stdio için bir kez giriş yapın, ardından istemcinizi skycloak-mcp run adresine yönlendirin:

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

Claude Desktop / Cursor (yerel, stdio):

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

Claude Code:

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

Başsız / CI (tarayıcısız) ortamlar için init adımını atlayın ve bunun yerine anahtarı iletin: yapılandırmaya "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } ekleyin veya claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio kullanın.

--allow-writes öğesini yalnızca değişiklik yapmayı planladığınızda ekleyin (skycloak-mcp init --allow-writes ile oturum açın veya yazma kapsamlı bir anahtar kullanın).

Barındırılan bir HTTP URL'sine ?readonly=true ekleyerek o HTTP oturumu için yalnızca salt okunur araçları açığa çıkarın veya yazma yetenekli araç yüzeyini istemek için ?readonly=false kullanın. Sorgu parametresi varsayılan olarak false değerindedir, ancak yazma araçları yalnızca sunucu --allow-writes ile başlatıldığında kaydedilir.

Bir OAuth oturumunun hangi çalışma alanı üzerinde çalışacağını seçmek için ?workspace=<uuid> ekleyin. Bu yalnızca birden fazla çalışma alanına ait olduğunuzda gereklidir; tek bir çalışma alanınız varsa sunucu sizin için onu seçer ve birden fazlasına ait olup hiçbirini belirtmezseniz, bağlantı bunları listeleyen bir mesajla başarısız olur.

HTTP taşıyıcısını çalıştırma

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

Kendine ait bir kimlik bilgisine ihtiyaç duymaz: çağıranlar her istekte kendi kimlik bilgilerini sağlar, bu nedenle dağıtım sırasında hiçbir şey enjekte edilmez. GET /healthz ve GET /readyz kimlik doğrulaması gerektirmez ve yalnızca sürecin çalıştığını bildirir; bilinçli olarak Skycloak API'sini yoklamazlar, böylece yukarı akıştaki bir aksaklık tüm kopyaların yoklamasını aynı anda başarısız kılamaz. Sunucu oturum durumu tutmaz, bu nedenle kopyalar oturum yakınlığı gerektirmez ve serbestçe ölçeklenebilir veya döndürülebilir. SIGTERM yeni bağlantıları durdurur ve devam eden çağrıları boşaltır.

OAuth yolu, SKYCLOAK_ISSUER ve SKYCLOAK_DASHBOARD_URL ayarlandığında etkindir; bunlar varsayılan olarak ayarlıdır. GET /.well-known/oauth-protected-resource daha sonra kimlik doğrulaması olmadan sunulur ve realm'i yetkilendirme sunucusu olarak adlandırır. resource değeri, ayarlandığında SKYCLOAK_PUBLIC_URL'den, aksi takdirde isteğin kendi Host ve şemasından alınır; böylece bir ingress arkasındaki tek ana bilgisayarlı dağıtım ek yapılandırma gerektirmez. Şema, mevcut olduğunda X-Forwarded-Proto'dan gelir ve aksi takdirde döngüsel (loopback) ana bilgisayar dışındakiler için https varsayılanını kullanır, çünkü TLS yukarı akışta sonlandırılır ve bir http:// tanımlayıcısı yayınlamak, istemcinin bağlandığı URL ile eşleşmez. Ingress'iniz Host değerini yeniden yazıyorsa SKYCLOAK_PUBLIC_URL ayarlayın. Belge ayrıca openid profile email değerini scopes_supported olarak listeler ve WWW-Authenticate sorgulaması bunları bir scope parametresi olarak tekrarlar; böylece ikisinden birini okuyan bir istemci bunları realm'den ister: openid zorunludur, çünkü belirteç değişimi panonun Keycloak'ın userinfo uç noktasını çağırmasını sağlar ve Keycloak onsuz verilen bir belirteci reddeder. Onsuz gelen bir belirteç, başarılı olamayacak bir değişime taşınmak yerine, doğrulamada bir 401 ve sorgulama ile reddedilir; böylece daha önce bir yetki (grant) tutan bir istemci yeniden denemeyi bırakır ve yeniden oturum açar. Veren (issuer) veya pano değişkenlerinden herhangi birini boşaltmak OAuth'u tamamen kapatır ve sunucu yalnızca bir API anahtarı için sorgulama yapmaya geri döner.

OPENAI_APPS_CHALLENGE_TOKEN, OpenAI'nin eklenti dizini alan doğrulama belirtecini /.well-known/openai-apps-challenge adresinde düz metin olarak sunar, başka hiçbir şey sunmaz. Ayarlanmadığında, rota kayıtlı değildir ve yol 404 döndürür.

Başlangıçta, çözdüğü bağlantı düzenini tek satırda günlüğe kaydeder (oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=); böylece yanlış yapılandırılmış bir dağıtım yeniden dağıtım yapılmadan fark edilebilir. OAuth yolunda reddedilen her istek, başarısız olan aşamayı (verify, exchange veya scopes), çağıranın aldığı durumu ve altta yatan hatayı adlandıran tek bir satır günlüğe kaydeder. Bir doğrulama hatası, belirteci reddeden kontrolü ekler (expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope vb.); bir değişim hatası, panonun durumunu ve çağrılan ana bilgisayarı ekler. Çağıran, belirteç doğrulandıktan sonra belirtecin konusu (subject) olarak görünür ve asla bir kimlik bilgisi olarak görünmez: erişim belirteci, Authorization başlığı ve üretilen API anahtarı asla günlüğe kaydedilmez.

Yapılandırma

Ortam değişkeni	Varsayılan
SKYCLOAK_API_KEY	yok (stdio için isteğe bağlı; HTTP istemcileri bunun yerine API-Key başlıkları sağlar)
SKYCLOAK_ENDPOINT	https://api.skycloak.io
SKYCLOAK_API_VERSION	güncel API sürümü
SKYCLOAK_ISSUER	https://login.app.skycloak.io/realms/skycloak (CLI oturumu ve HTTP taşıyıcısının belirteçleri doğruladığı yetkilendirme sunucusu)
SKYCLOAK_CLIENT_ID	skycloak-mcp (yalnızca CLI cihaz akışı)
SKYCLOAK_DASHBOARD_URL	https://app.skycloak.io (CLI anahtarları ve HTTP oturum anahtarları üretir)
SKYCLOAK_PUBLIC_URL	yok (her istekten türetilir; ingress Host değerini yeniden yazdığında ayarlayın)
OPENAI_APPS_CHALLENGE_TOKEN	OpenAI'nin eklenti dizini doğrulama belirtecini /.well-known/openai-apps-challenge adresinde sunar. Ayarlanmadığında, bu yol 404 döndürür.

Komutlar: init (tarayıcı oturumu), run (sunma), logout (depolanan anahtarı kaldırma). init şunları kabul eder: --workspace <id>, --allow-writes, --allow-credentials ve --ttl-days (varsayılan 90).

Bayrak	Varsayılan	Açıklama
--transport	stdio	stdio veya http
--http-addr	:8080	HTTP taşıyıcısı için dinleme adresi
--allow-writes	false	stdio için değiştirici (mutating) araçları etkinleştirir ve readonly=false ile HTTP oturumlarının yazma araçları kaydetmesine izin verir

Geliştirme

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 altındaki API istemcisi, Skycloak OpenAPI belirtiminden oapi-codegen ile üretilir.

API ile senkronize tutma

internal/apiclient içindeki istemci, internal/apiclient/openapi.yaml dosyasından oapi-codegen ile üretilir; yenilemek için make generate çalıştırın. Taahhüt edilen üretilen kod belirtimden saparsa CI başarısız olur. İstekler 429/5xx üzerinde Retry-After farkındalıklı geri tepme (backoff) ile yeniden denenir.

Dağıtım

Her etikette GitHub ikili dosyaları ve bir ghcr.io/sky-cloak/skycloak-mcp konteyner görüntüsü olarak yayınlanır ve MCP Registry üzerinde io.skycloak/skycloak-mcp olarak yayımlanır. Çoğu kişinin ikisine de ihtiyacı yoktur: barındırılan sunucu kurulum gerektirmez.

Güvenlik

Lütfen güvenlik açıklarını özel olarak bildirin. SECURITY.md dosyasına bakın.

Katkıda Bulunanlar

Skycloak bünyesinde Guilliano Molaire, Neville Omangi ve Aphilas tarafından geliştirilmiştir. Depo geçmişi açıldığında sıkıştırıldığı (squash) için, taahhüt günlüğü kimin ne yazdığını yansıtmaz.

Lisans

Apache-2.0. internal/apiclient/openapi.yaml içindeki OpenAPI açıklaması Skycloak platform API'sinden üretilir ve (c) Skycloak'a aittir; istemcinin üretilip doğrulanabilmesi için buraya dahil edilmiştir. NOTICE dosyasına bakın.