Keycloak MCP Server

Ein Model Context Protocol (MCP) Server, der eine natürlichsprachliche Schnittstelle zur Verwaltung von Keycloak Identitäts- und Zugriffsmanagement über dessen REST-API bereitstellt. Dieser Server ermöglicht es KI-Agenten, Benutzerverwaltung, Client-Konfiguration, Realm-Administration und rollenbasierte Zugriffskontrollen nahtlos durchzuführen.

Übersicht

Der Keycloak MCP Server schließt die Lücke zwischen KI-Anwendungen und den leistungsstarken Identitätsverwaltungsfunktionen von Keycloak. Egal, ob Sie einen KI-Assistenten entwickeln, der Benutzer verwalten, Clients konfigurieren oder komplexe Autorisierungsszenarien handhaben muss – dieser Server bietet die benötigten Werkzeuge durch einfache, natürlichsprachliche Befehle.

Related MCP server: Advanced Keycloak MCP server

Funktionen

🔐 Umfassende Benutzerverwaltung

Verwalten Sie den Lebenszyklus von Benutzern von der Erstellung bis zur Löschung, einschließlich Passwort-Resets, Sitzungsverwaltung und Aktualisierungen von Benutzerattributen.

🏢 Client-Konfiguration

Erstellen und konfigurieren Sie OAuth2/OIDC-Clients, verwalten Sie Client-Secrets und handhaben Sie Service-Accounts programmatisch.

👥 Rollenbasierte Zugriffskontrolle (RBAC)

Definieren und weisen Sie Realm- und Client-spezifische Rollen zu, verwalten Sie Benutzerberechtigungen und implementieren Sie eine fein abgestufte Zugriffskontrolle.

🏛️ Realm-Administration

Konfigurieren Sie Realm-Einstellungen, verwalten Sie Standardgruppen, handhaben Sie Ereigniskonfigurationen und steuern Sie Realm-weite Richtlinien.

🔐 Authentifizierungsverwaltung

Umfassende Verwaltung von Authentifizierungsabläufen, einschließlich Erstellung, Aktualisierung und Löschung von Abläufen, Verwaltung von Ausführungen und Konfiguration von Authentifikatoren.

🔄 Gruppenverwaltung

Organisieren Sie Benutzer in Gruppen, verwalten Sie Gruppenhierarchien und handhaben Sie gruppenbasierte Berechtigungen effizient.

Installation

Installation via Smithery

Um mcp-keycloak automatisch für Claude Desktop über Smithery zu installieren:

npx -y @smithery/cli install mcp-keycloak --client claude

Schnellstart

Installation mittels pip:

pip install mcp-keycloak

Entwicklungsinstallation

Klonen Sie das Repository und installieren Sie die Abhängigkeiten:

git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak
pip install -e .

Konfiguration

Der Server kann über Umgebungsvariablen oder eine .env-Datei konfiguriert werden:

# Required configuration
SERVER_URL=https://your-keycloak-server.com
USERNAME=admin-username
PASSWORD=admin-password
REALM_NAME=your-realm

# Optional OAuth2 client configuration
CLIENT_ID=optional-client-id
CLIENT_SECRET=optional-client-secret

Werkzeuge

Der Keycloak MCP Server bietet eine umfassende Reihe von Werkzeugen, die nach Funktionalität organisiert sind:

Benutzerverwaltung

Komplette Verwaltung des Benutzerlebenszyklus, einschließlich:

• list_users - Benutzer mit Paginierung und Filterung auflisten

• create_user / update_user / delete_user - Vollständige CRUD-Operationen

• reset_user_password - Passwortverwaltung

• get_user_sessions / logout_user - Sitzungskontrolle

• count_users - Benutzerstatistiken

Client-Verwaltung

OAuth2/OIDC-Client-Konfiguration:

• list_clients / get_client / create_client - Client-Operationen

• get_client_secret / regenerate_client_secret - Secret-Verwaltung

• get_client_service_account - Zugriff auf Service-Accounts

• update_client / delete_client - Client-Modifikationen

Rollenverwaltung

Fein abgestufte Berechtigungskontrolle:

• list_realm_roles / create_realm_role - Realm-Rollen-Operationen

• list_client_roles / create_client_role - Client-spezifische Rollen

• assign_realm_role_to_user / remove_realm_role_from_user - Rollenzuweisungen

• get_user_realm_roles / assign_client_role_to_user - Abfragen von Benutzerrollen

Gruppenverwaltung

Hierarchische Benutzerorganisation:

• list_groups / create_group / update_group - Gruppenoperationen

• get_group_members / add_user_to_group - Mitgliedschaftsverwaltung

• get_user_groups / remove_user_from_group - Benutzer-Gruppen-Zuordnungen

Realm-Administration

Systemweite Konfiguration:

• get_accessible_realms - Liste der zugänglichen Realms

• get_realm_info / update_realm_settings - Realm-Konfiguration

• get_realm_events_config / update_realm_events_config - Ereignisverwaltung

• add_realm_default_group / remove_realm_default_group - Standardeinstellungen

Authentifizierungsverwaltung

Komplette Kontrolle über Authentifizierungsabläufe:

• list_authentication_flows / get_authentication_flow - Ablaufverwaltung

• create_authentication_flow / update_authentication_flow - Ablauf-CRUD-Operationen

• delete_authentication_flow / copy_authentication_flow - Ablaufmodifikationen

• get_flow_executions / update_flow_executions - Ausführungsverwaltung

• create_execution / delete_execution - Lebenszyklus von Ausführungen

• get_authenticator_config / create_authenticator_config - Konfigurationsverwaltung

• get_required_actions / update_required_action - Kontrolle erforderlicher Aktionen

Verwendung

Ausführen des Servers

Der Server unterstützt sowohl stdio (Standard) als auch HTTP-Transporte. Die Konfigurationsdatei smithery.yaml ermöglicht die Bereitstellung auf der Smithery-Plattform und die automatische Installation über die Smithery CLI:

# Run in stdio mode (default, for local CLI tools)
python -m src.main

# Run in HTTP mode with streamable HTTP transport
TRANSPORT=http python -m src.main

# Run HTTP mode on a custom port
TRANSPORT=http PORT=8080 python -m src.main

# Or use the convenience script:
./scripts/run_server.sh         # stdio mode (default)
./scripts/run_server.sh http    # HTTP mode
PORT=8080 ./scripts/run_server.sh http  # HTTP mode on custom port

Bei Verwendung des HTTP-Transports ist der Server unter http://127.0.0.1:8000/mcp/ (oder Ihrem benutzerdefinierten PORT) erreichbar.

HTTP-Transport

Der Keycloak MCP Server unterstützt den HTTP-Transportmodus, der mehrere Vorteile bietet:

• Netzwerkzugänglichkeit: Zugriff auf den Server von jedem Gerät in Ihrem Netzwerk

• Mehrere Clients: Unterstützung gleichzeitiger Verbindungen von mehreren KI-Clients

• Integrationsflexibilität: Einfache Integration in Webanwendungen und APIs

• Lastverteilung: Bereitstellung hinter einem Reverse-Proxy für Skalierbarkeit

Details zum HTTP-Protokoll

Der HTTP-Transport folgt der MCP-Spezifikation für Streamable HTTP. FastMCP handhabt automatisch alle Protokollanforderungen:

• Endpunkt: Die gesamte Kommunikation erfolgt über den /mcp/-Endpunkt

• Anfragemethode: POST-Anfragen mit JSON-RPC 2.0-Nachrichten

• Inhaltstypen:

  • Der Server gibt Content-Type: application/json für einzelne Antworten zurück

  • Der Server gibt Content-Type: text/event-stream für Streaming-Antworten zurück

• Accept-Header: Clients müssen Accept: application/json, text/event-stream enthalten

• Nachrichtenformat: Alle Nachrichten verwenden das JSON-RPC 2.0-Format, UTF-8 kodiert

FastMCP bestimmt automatisch basierend auf dem Anfragetyp und ob die Antwort Streaming-Fähigkeiten erfordert, ob eine einzelne JSON-Antwort oder ein SSE-Stream zurückgegeben werden soll.

Verbindung zum HTTP-Server

Im HTTP-Modus können sich Clients wie folgt verbinden:

http://127.0.0.1:8000/mcp/

Beispiel für eine Client-Anfrage:

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "list_tools", "id": 1}'

Sicherheitsimplementierung

Der HTTP-Transport implementiert alle Sicherheitsanforderungen der MCP-Spezifikation:

✅ Validierung des Origin-Headers (ERFORDERLICH)

• Validiert automatisch Origin-Header, um DNS-Rebinding-Angriffe zu verhindern

• Erlaubt nur Verbindungen von localhost und 127.0.0.1-Ursprüngen

• Blockiert nicht autorisierte Cross-Origin-Anfragen

✅ Localhost-Bindung (EMPFOHLEN)

• Bindet nur an 127.0.0.1, um netzwerkbasierte Angriffe zu verhindern

• Folgt den Sicherheitsempfehlungen der MCP-Spezifikation

✅ Keine Authentifizierung erforderlich

• Der Server läuft ohne Authentifizierungsanforderungen für eine vereinfachte lokale Entwicklung

• Geeignet für die Nutzung auf localhost und in vertrauenswürdigen Umgebungen

Für Produktionsbereitstellungen sind zusätzliche Überlegungen erforderlich:

• Verwendung von HTTPS mit ordnungsgemäßen Zertifikaten

• Bereitstellung hinter einem Reverse-Proxy (nginx, Apache)

• Festlegen geeigneter Firewall-Regeln

• Implementierung einer Authentifizierung auf Ebene des Reverse-Proxys, falls erforderlich

Integrationsbeispiele

Voraussetzungen

Stellen Sie vor der Integration des Keycloak MCP Servers sicher, dass eines der folgenden Programme installiert ist:

• uvx (empfohlen): Installation über pip install uvx oder pipx install uvx

• uv: Folgen Sie den Installationsanweisungen

• npm/npx: Für die Smithery-Installation (wird mit Node.js geliefert)

Option 1: Verwendung der Smithery CLI (Empfohlen)

Der einfachste Weg – konfiguriert automatisch alles für Claude Desktop:

npx @smithery/cli install @idoyudha/mcp-keycloak --client claude

Dieser Befehl fragt Sie nach den erforderlichen Konfigurationswerten und richtet den Server automatisch ein.

Option 2: Verwendung von uvx (Manuelle Einrichtung)

Kein Klonen erforderlich! Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "keycloak": {
      "command": "uvx",
      "args": ["mcp-keycloak"],
      "env": {
        "SERVER_URL": "https://your-keycloak.com",
        "USERNAME": "admin",
        "PASSWORD": "admin-password",
        "REALM_NAME": "your-realm"
      }
    }
  }
}

Option 3: Lokale Entwicklungseinrichtung

Für Entwicklung oder Anpassungen:

1. Klonen Sie das Repository:

git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak

2. Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "keycloak": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-keycloak",
        "run",
        "python",
        "-m",
        "src"
      ],
      "env": {
        "SERVER_URL": "https://your-keycloak.com",
        "USERNAME": "admin",
        "PASSWORD": "admin-password",
        "REALM_NAME": "your-realm"
      }
    }
  }
}

💡 Kurztipps:

• Ersetzen Sie /path/to/mcp-keycloak durch den tatsächlichen Pfad, in den Sie das Repository geklont haben

• Stellen Sie sicher, dass Ihre Keycloak-Server-URL das Protokoll (https:// oder http://) enthält

• Der REALM_NAME sollte mit einem existierenden Realm in Ihrer Keycloak-Instanz übereinstimmen

Anwendungsbeispiele

🤖 KI-gestützte Identitätsverwaltung

Erstellen Sie KI-Assistenten, die Benutzer-Onboarding, Berechtigungsverwaltung und Zugriffskontrolle durch natürlichsprachliche Befehle handhaben können.

🔄 Automatisierte Benutzerbereitstellung

Erstellen Sie Workflows, die Benutzer automatisch bereitstellen, Rollen zuweisen und Client-Anwendungen basierend auf Geschäftsregeln konfigurieren.

📊 Identitätsanalyse

Fragen und analysieren Sie Benutzerdaten, Sitzungsinformationen und Zugriffsmuster, um Einblicke in Ihre Identitätsinfrastruktur zu gewinnen.

🚀 DevOps-Integration

Integrieren Sie die Keycloak-Verwaltung in Ihre CI/CD-Pipelines, was eine automatisierte Konfiguration von Identitätsdiensten ermöglicht.

Anforderungen

• Python 3.8 oder höher

• Keycloak-Server (getestet mit Keycloak 18+)

• Administratorzugriff auf den Keycloak-Realm

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe die LICENSE-Datei für Details.

Mitwirken

Beiträge sind willkommen! Bitte fühlen Sie sich frei, einen Pull Request einzureichen.

Support

Für Probleme, Fragen oder Beiträge besuchen Sie bitte das GitHub-Repository.