mcp-keycloak

Ein Model Context Protocol-Server für Keycloak. Er ermöglicht einem MCP-fähigen Client (Claude Desktop, Claude Code, etc.), die Realms, Benutzer, Clients, Rollen und Gruppen von Keycloak einzusehen und zu verwalten — wobei die Sicherheit vollständig über Flags gesteuert wird.

Das Designziel ist standardmäßig sicher: Der Server startet im Nur-Lesen-Modus, beschränkt sich auf eine Allowlist von Realms, schützt sensible Realms vor Änderungen und macht destruktive Operationen von einem expliziten Opt-in abhängig.

Features

• Multi-Realm — jedes Tool nimmt ein realm-Argument entgegen; begrenzen Sie es mit einer Allowlist.

• Zugriffsmodi — read-only → read-write → admin, geschichtet, sodass ein Modus nie Tools oberhalb seiner Stufe bereitstellt.

• Sicherheits-Flags — Realm-Allowlist, geschützte Realms, Steuerung von Löschvorgängen, Dry-Run und JSON-Audit-Logging (siehe unten).

• Zwei Authentifizierungsstrategien — Servicekonto eines Confidential-Clients (empfohlen) oder Admin-Benutzername/Passwort.

• Keine schwergewichtigen Abhängigkeiten — ein schlanker fetch-basierter Admin-REST-Client plus das MCP-SDK und zod.

Related MCP server: mcp-keycloak-admin

Sicherheitsmodell

Diese Ebenen sind unabhängig — beispielsweise kann der admin-Modus bei KEYCLOAK_ALLOW_DELETE=false Benutzer erstellen und aktualisieren, aber nicht löschen.

Werkzeuge

• Lesen (read-only+): list_realms, get_realm, list_users, get_user, count_users, list_clients, list_realm_roles, list_groups

• Schreiben (read-write+): create_user, update_user, reset_password, logout_user

• Admin (admin): delete_user

Verwendung mit Ihrem MCP-Client

Funktioniert mit Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Windsurf, VS Code (Copilot) und jedem anderen MCP-Client — siehe docs/CLIENTS.md für die Einrichtung pro Client.

Installation

npm install
npm run build

Konfiguration

Kopieren Sie .env.example und füllen Sie die Datei aus, oder setzen Sie die Variablen direkt in Ihrer MCP-Client-Konfiguration. Die empfohlene Möglichkeit für Anmeldedaten ist ein ConfidentialityBenutzereintritt mit den realm-management-Rollen, die Sie benötigen.

Ausführen mit Claude Desktop / Claude Code

Fügen Sie es zu Ihrer MCP-Client-Konfiguration hinzu (claude_desktop_config.json oder über claude mcp add):

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-keycloak/dist/index.js"],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only",
        "KEYCLOAK_REALM_ALLOWLIST": "app,customers"
      }
    }
  }
}

Setzen Sie KEYCLOAK_MODE auf read-write (und für Löschvorgänge auf admin + KEYCLOAK_ALLOW_DELETE=true) nur dann, wenn Sie dem Modell erlauben möchten, Änderungen vorzunehmen.

Entwicklung

npm run dev        # watch mode
npm test           # unit tests for the security policy
npm run typecheck

Veröffentlichung

Dieser Server wird mit einer server.json für die offizielle MCP-Registry und einem mcpName zur Bestätigungierung der npm-Inhaberschaft ausgeliefert. Siehe PUBLISHING.md für das Veröffentlichen auf npm und die Aufnahme in die MCP-Registry, bei Smithery, Glama, Cursor und PulseMCP.

Lizenz

MIT