skycloak-mcp

Offizieller Model Context Protocol-Server für Skycloak (verwaltetes Keycloak): Verwalten Sie Ihre Cluster, Realms, Anwendungen und SSO über jeden MCP-Client (Claude Desktop, Claude Code, Cursor).

Status: frühe Veröffentlichung. Die Tool-Abdeckung wächst; sehen Sie sich das Changelog an, um zu erfahren, was verfügbar ist.

Quick start

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

Kein API-Schlüssel, keine Client-ID, keine Konfiguration. Ihr Browser öffnet sich, Sie melden sich bei Skycloak an, und die Tools erscheinen. Jeder MCP-Client, der streamable HTTP unterstützt, funktioniert auf die gleiche Weise: Geben Sie die URL an und sonst nichts.

Dann fragen Sie nach etwas:

• "Welche meiner Keycloak-Cluster sind bei Upgrades im Rückstand?"

• "Erstellen Sie ein Staging-Realm auf dem EU-Cluster mit Google- und GitHub-Anmeldung."

• "Wer wurde in der letzten Woche zum Produktions-Realm hinzugefügt?"

• "Richten Sie ein SIEM-Ziel ein, das Admin-Events an unseren Datadog-Webhook weiterleitet."

Related MCP server: MCP Authentik

Authentifizierung & Sicherheit

• Gehostetes HTTP, mit OAuth (keine Anmeldedaten zum Konfigurieren). Weisen Sie Ihren Client auf https://mcp.skycloak.io an, ohne Header. Der Server antwortet mit 401 und einem Verweis auf seine RFC 9728-Metadaten unter /.well-known/oauth-protected-resource, der Client führt den Browser-Autorisierungscode-Flow gegen das Skycloak-Login-Realm aus, und das erhaltene Zugriffstoken wird gegen einen kurzlebigen, workspace-bezogenen API-Schlüssel ausgetauscht, auf dem die Sitzung läuft. Der Schlüssel ist eine Stunde gültig und wird automatisch erneuert. Nichts wird in Ihrer Client-Konfiguration gespeichert.

• Gehostetes HTTP, mit einem API-Schlüssel. Erstellen Sie einen Schlüssel im Skycloak-Dashboard und senden Sie ihn als Authorization: Bearer <key> (oder API-Key: <key>). Jede Anfrage trägt ihre eigene Anmeldeinformation und agiert nur als der Workspace dieser Anmeldeinformation. Der Server behält keinen Sitzungszustand, sodass eine Anfrage niemals die eines anderen Aufrufers erbt. Schlüssel werden vor der Verwendung nicht überprüft: Die Skycloak-API ist die Autorität, sodass ein ungültiger Schlüssel beim ersten Tool-Aufruf als 401 erscheint, nicht beim Verbindungsaufbau.

• Tools passen zu Ihrer Rolle. Bei OAuth wird die Tool-Liste auf das reduziert, was die Sitzungsberechtigungen erlauben, sodass einem schreibgeschützten Workspace-Mitglied keine Schreib-Tools angezeigt werden, die mit 403 antworten würden. Mit einem API-Schlüssel wird die gesamte Oberfläche registriert, da die Berechtigungen eines Schlüssels für den Server nicht sichtbar sind, und ein nicht autorisierter Aufruf erscheint als 403 von der API.

• Lokales stdio. Führen Sie skycloak-mcp init aus und bestätigen Sie in Ihrem Browser (OAuth 2.0-Geräteautorisierungs-Flow). Es erstellt einen workspace-bezogenen API-Schlüssel, speichert ihn in Ihrer Betriebssystem-Tasche (keychain) und erkennt automatisch Ihren Standard-Workspace (übergeben Sie --workspace <id>, um einen anderen auszuwählen). skycloak-mcp logout entfernt den gespeicherten Schlüssel.

• Headless / CI. Setzen Sie die Umgebungsvariable SKYCLOAK_API_KEY (erstellen Sie einen Schlüssel im Skycloak-Dashboard), um den Browser vollständig zu überspringen. Sie hat immer Vorrang vor der Schlüsseltasche.

• Schreibvorgänge werden durch Ihre Anmeldeinformation gesteuert, nicht durch ein Flag. Der gehostete Server unter https://mcp.skycloak.io läuft schreibfähig, und was Sie tatsächlich ändern können, wird durch die Berechtigungen Ihres Schlüssels und Ihre Workspace-Rolle begrenzt: Ein schreibgeschütztes Mitglied kann nichts ändern, egal was die Tool-Liste sagt. Fügen Sie ?readonly=true zur URL hinzu, um für eine Sitzung eine schreibgeschützte Tool-Oberfläche zu erzwingen. Das lokale Binary ist genau umgekehrt und registriert keine Schreib-Tools, es sei denn, es wird mit --allow-writes gestartet.

• Cluster-Anmeldeinformationen sind opt-in. get_cluster_credentials gibt die Keycloak-Admin-Anmeldeinformationen eines Clusters zurück, die ein den Schlüssel haltender Assistent dann sehen würde, daher fordert init diesen Bereich standardmäßig nicht an. Verwenden Sie einen Schlüssel, der diesen Bereich enthält: Erstellen Sie einen im Dashboard, oder melden Sie sich über stdio mit skycloak-mcp init --allow-credentials an. Ohne diesen gibt das Tool einen 403 zurück, der beide Wege erklärt.

• Zerstörerische Tools erfordern Bestätigung: Das Löschen eines Realms erfordert beispielsweise ein explizites confirm=true-Argument.

• Anfragen werden gemäß Ihrem Skycloak-Plan ratenbegrenzt; bei einer 429-Antwort gibt der Server Retry-After an.

Tools

129 Tools: 58 schreibgeschützt und 71 schreibend. Schreibgeschützte Tools sind immer verfügbar. Auf dem gehosteten Server werden die Schreib-Tools ebenfalls registriert und durch die Berechtigungen Ihrer Anmeldeinformation gesteuert; das lokale Binary registriert sie nur, wenn es mit --allow-writes gestartet wird.

Tool-Namen tragen ein skycloak_-Präfix, das die folgende Tabelle weglässt, daher ist list_clusters in Ihrem Client skycloak_list_clusters.

Konventionen: Zerstörerische Werkzeuge (delete_*, uninstall_extension, cancel_cluster_upgrade) erfordern confirm=true. create_cluster ist asynchron: Pollen Sie get_cluster, bis der Cluster available ist. create_domain gibt die DNS-Einträge zurück, die der Kunde erstellen muss; verify_domain löst eine DNS-Überprüfung aus. set_theme_assignment aktiviert ein benutzerdefiniertes Theme pro Keycloak-Theme-Typ (leerer String setzt auf das eingebaute Standard-Theme zurück). update_cluster_security lässt CAPTCHA-Einstellungen unberührt. Bereichsimport/-export verschiebt die Konfiguration eines Bereichs und ist getrennt von create_export, das die gesamte Datenbank eines Clusters sichert: Beide sind asynchron, und das Bereichsarchiv ist immer verschlüsselt, daher wird das Passwort, das zum Exportieren verwendet wurde, zum erneuten Importieren benötigt. Ein Bereich kann direkt aus einem vorhandenen Export (source_export_id) oder aus einem hochgeladenen Archiv (create_realm_import_upload_url, PUT, dann upload_s3_key) importiert werden; das Importieren erstellt einen Bereich und verweigert eine Namenskollision anstatt zu überschreiben, und benötigt confirm=true, da es Benutzer und Anmeldeinformationen mitbringt.

Verbinden

Für gehostetes HTTP ist der einfachste Weg OAuth, der überhaupt keine Anmeldeinformationen benötigt:

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

Der erste Aufruf öffnet Ihren Browser, Sie bestätigen auf der Skycloak-Anmeldeseite, und die Werkzeuge erscheinen. Wenn Sie zu mehr als einem Arbeitsbereich gehören, geben Sie den gewünschten an:

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

Andernfalls erstellen Sie einen API-Schlüssel im Skycloak-Dashboard und konfigurieren Sie Ihren MCP-Client so, dass er ihn als Bearer-Token sendet:

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

Dies fügt Folgendes zu .claude.json hinzu:

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

Für lokales stdio melden Sie sich einmal an und weisen dann Ihren Client auf skycloak-mcp run an:

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

Claude Desktop / Cursor (lokal, stdio):

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

Claude Code:

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

Für headless / CI (kein Browser) überspringen Sie init und übergeben Sie stattdessen den Schlüssel: Fügen Sie "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } zur Konfiguration hinzu, oder claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio.

Fügen Sie --allow-writes nur hinzu, wenn Sie Änderungen vornehmen möchten (melden Sie sich mit skycloak-mcp init --allow-writes an oder verwenden Sie einen Schlüssel mit Schreibberechtigung).

Fügen Sie ?readonly=true zu einer gehosteten HTTP-URL hinzu, um nur schreibgeschützte Werkzeuge für diese HTTP-Sitzung verfügbar zu machen, oder ?readonly=false, um die schreibfähige Werkzeugoberfläche anzufordern. Der Abfrageparameter hat standardmäßig den Wert false, aber Schreibwerkzeuge werden nur registriert, wenn der Server mit --allow-writes gestartet wurde.

Fügen Sie ?workspace=<uuid> hinzu, um auszuwählen, auf welchen Workspace eine OAuth-Sitzung wirkt. Es wird nur benötigt, wenn Sie mehr als einem Workspace angehören; bei einem einzelnen Workspace wählt der Server ihn für Sie aus. Wenn Sie mehreren angehören und keinen nennen, schlägt die Verbindung mit einer Nachricht fehl, die diese auflistet.

Running the HTTP transport

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

Es benötigt keine eigenen Anmeldeinformationen: Aufrufer liefern ihre pro Anfrage, sodass zum Zeitpunkt der Bereitstellung nichts injiziert wird. GET /healthz und GET /readyz sind nicht authentifiziert und melden nur, dass der Prozess läuft; sie testen bewusst nicht die Skycloak-API, sodass eine kurzzeitige Störung eines vorgelagerten Dienstes nicht gleichzeitig die Prüfung aller Replikate zum Scheitern bringen kann. Der Server speichert keinen Sitzungszustand, daher benötigen Replikate keine Sitzungsaffinität und können frei skaliert oder aktualisiert werden. SIGTERM stoppt neue Verbindungen und lässt laufende Aufrufe auslaufen.

Der OAuth-Pfad ist aktiv, sobald SKYCLOAK_ISSUER und SKYCLOAK_DASHBOARD_URL gesetzt sind, was standardmäßig der Fall ist. GET /.well-known/oauth-protected-resource wird dann ohne Authentifizierung bereitgestellt und benennt den Realm als den Autorisierungsserver. Sein resource-Wert wird aus SKYCLOAK_PUBLIC_URL übernommen, falls gesetzt, andernfalls aus dem Host- und Schema des Requests, sodass eine Einzelhost-Bereitstellung hinter einem Ingress keine zusätzliche Konfiguration benötigt. Das Schema stammt aus X-Forwarded-Proto, falls vorhanden, andernfalls wird für alles außer einem Loopback-Host standardmäßig https verwendet, da TLS vorgelagert terminiert wird und die Veröffentlichung eines http://-Identifiers nicht mit der URL übereinstimmen würde, mit der der Client verbunden ist. Setzen Sie SKYCLOAK_PUBLIC_URL, wenn Ihr Ingress Host umschreibt. Das Dokument listet auch openid profile email als seine scopes_supported auf, und die WWW-Authenticate-Challenge wiederholt sie als scope-Parameter, sodass ein Client, der eines davon liest, den Realm danach fragt: openid ist erforderlich, da der Token-Austausch das Dashboard veranlasst, den Keycloak-Userinfo-Endpunkt aufzurufen, und Keycloak einen ohne diesen gewährten Token ablehnt. Ein Token, der ohne diesen ankommt, wird bei der Verifizierung mit einem 401 und der Challenge abgelehnt, anstatt zu einem Austausch geführt zu werden, der nicht erfolgreich sein kann, sodass ein Client, der noch ein älteres Grant besitzt, die Wiederholungsversuche einstellt und sich erneut anmeldet. Das Leeren entweder der Issuer- oder der Dashboard-Variablen schaltet OAuth vollständig aus, und der Server fordert wieder nur einen API-Schlüssel an.

Beim Start wird eine Zeile mit der aufgelösten Verkabelung protokolliert (oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=), sodass eine fehlkonfigurierte Bereitstellung ohne erneutes Ausrollen erkannt werden kann. Jede im OAuth-Pfad abgelehnte Anfrage protokolliert eine Zeile mit der fehlgeschlagenen Stufe (verify, exchange oder scopes), dem Status, den der Aufrufer erhielt, und dem zugrunde liegenden Fehler. Ein Verifizierungsfehler fügt die Prüfung hinzu, die den Token abgelehnt hat (expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope usw.); ein Austauschfehler fügt den Status des Dashboards und den aufgerufenen Host hinzu. Der Aufrufer erscheint nach der Verifizierung als Subjekt des Tokens und nie als Anmeldeinformation: Das Zugriffstoken, der Authorization-Header und der generierte API-Schlüssel werden nie protokolliert.

Configuration

Befehle: init (Browser-Anmeldung), run (Bereitstellen), logout (gespeicherten Schlüssel entfernen). init akzeptiert --workspace <id>, --allow-writes, --allow-credentials und --ttl-days (Standard 90).

Development

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

Der API-Client unter internal/apiclient wird aus der Skycloak-OpenAPI-Spezifikation mit oapi-codegen generiert.

Keeping in sync with the API

Der Client in internal/apiclient wird aus internal/apiclient/openapi.yaml mit oapi-codegen generiert; führen Sie make generate aus, um ihn zu aktualisieren. CI schlägt fehl, wenn der eingecheckte generierte Code von der Spezifikation abweicht. Anfragen werden bei 429/5xx mit Retry-After-bewusstem Backoff wiederholt.

Distribution

Wird als GitHub-Binärdateien und ein ghcr.io/sky-cloak/skycloak-mcp-Container-Image zu jedem Tag veröffentlicht und im MCP Registry als io.skycloak/skycloak-mcp veröffentlicht. Die meisten Leute benötigen keines von beiden: Der gehostete Server benötigt keine Installation.

Security

Bitte melden Sie Sicherheitslücken vertraulich. Siehe SECURITY.md.

Contributors

Erstellt bei Skycloak von Guilliano Molaire, Neville Omangi und Aphilas. Die Repository-Historie wurde beim Öffnen zusammengefasst, sodass das Commit-Log nicht widerspiegelt, wer was geschrieben hat.

License

Apache-2.0. Die OpenAPI-Beschreibung in internal/apiclient/openapi.yaml wird aus der Skycloak-Plattform-API generiert und ist (c) Skycloak; sie ist hier enthalten, damit der Client generiert und verifiziert werden kann. Siehe NOTICE.