Serveur MCP Octodet Keycloak

Un puissant serveur Model Context Protocol pour l'administration de Keycloak, fournissant un ensemble complet d'outils pour gérer les utilisateurs, les domaines, les rôles et d'autres ressources Keycloak par le biais d'interfaces LLM.

Caractéristiques

• Gestion des utilisateurs: Création, suppression et liste d'utilisateurs dans les domaines
• Administration des royaumes: Capacités complètes de gestion des royaumes
• Intégration sécurisée: Authentification avec les informations d'identification de l'administrateur
• Configuration facile: Installation simple avec des variables d'environnement
• Intégration LLM: Utilisation transparente avec Claude, ChatGPT, et d'autres assistants IA compatibles MCP

Installation de l'application

Via NPM (recommandé)

Le serveur est disponible sous forme de paquetage NPM :

# Utilisation directe avec npx npx -y @octodet/keycloak-mcp # Ou installation globale npm install -g @octodet/keycloak-mcp

Configuration de l'environnement

Variables d'environnement

Configuration du client MCP

Code VS

Ajoutez ceci à votre settings.json:

{ "mcp.servers" : { "keycloak" : {"command" : "npx", "args" : ["-y", "@octodet/keycloak-mcp"], "env" : { "KEYCLOAK_URL" : "http://localhost:8080", "KEYCLOAK_ADMIN" : "admin", "KEYCLOAK_ADMIN_PASSWORD" : "admin" } } }

Claude Desktop

Configurez dans votre fichier de configuration Claude Desktop :

{ "mcpServers" : { "keycloak" : { "command" : "npx", "args" : ["-y", "@octodet/keycloak-mcp"], "env" : { "KEYCLOAK_URL" : "http://localhost:8080", "KEYCLOAK_ADMIN" : "admin", "KEYCLOAK_ADMIN_PASSWORD" : "admin" } } }

Pour le développement local

{ "mcpServers" : { "keycloak" : { "command" : "node", "args" : ["path/to/build/index.js"], "env" : { "KEYCLOAK_URL" : "http://localhost:8080", "KEYCLOAK_ADMIN" : "admin", "KEYCLOAK_ADMIN_PASSWORD" : "admin" } } }

Outils disponibles

Le serveur fournit un ensemble complet d'outils MCP pour l'administration de Keycloak. Chaque outil est conçu pour effectuer des tâches administratives spécifiques dans les domaines, les utilisateurs et les rôles.

📋 Présentation des outils

👥 Gestion des utilisateurs

create-user

Crée un nouvel utilisateur dans un domaine spécifié avec des attributs d'utilisateur complets et des informations d'identification facultatives.

Paramètres requis :

• realm (chaîne) : Nom de la zone cible
• username (chaîne) : Nom d'utilisateur unique pour le nouvel utilisateur
• email (chaîne) : Adresse électronique valide
• firstName (chaîne) : Prénom de l'utilisateur
• lastName (chaîne) : Nom de l'utilisateur

Paramètres optionnels :

• enabled (booléen) : Active/désactive le compte de l'utilisateur (par défaut : true)
• emailVerified (booléen) : Marquer l'email comme vérifié
• credentials (tableau) : Tableau d'objets d'identification pour la définition des mots de passe

Structure de l'objet Credential :

• type (chaîne) : Type d'identifiant (par exemple, "mot de passe")
• value (chaîne) : La valeur de l'identifiant
• temporary (booléen) : Indique si le mot de passe doit être modifié lors de la première connexion

Exemple d'utilisation :

{"realm" : "my-app-realm", "username" : "john.doe", "email" : "john.doe@company.com", "firstName" : "John", "lastName" : "Doe", "enabled" : true, "emailVerified" : true, "credentials" : [ { "type" : "password", "value" : "TempPassword123 !", "temporary" : true } ] }

Réponse : Renvoie l'identifiant de l'utilisateur créé et le message de confirmation.

delete-user

Supprime définitivement un utilisateur du domaine spécifié. Cette action ne peut pas être annulée.

Paramètres requis :

• realm (chaîne) : Nom de la zone cible
• userId (chaîne) : Identifiant unique de l'utilisateur à supprimer

Exemple d'utilisation :

{"realm" : "my-app-realm", "userId" : "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c"
}

Réponse : Message de confirmation de la suppression réussie.

⚠️ Avertissement : Cette opération est irréversible. Assurez-vous d'avoir l'identifiant correct de l'utilisateur avant de l'exécuter.

list-users

Permet d'obtenir la liste de tous les utilisateurs du domaine spécifié, ainsi que leurs informations de base.

Paramètres requis :

• realm (chaîne) : Nom de la zone cible

Exemple d'utilisation :

{ "realm" : "my-app-realm" }

Réponse : Renvoie une liste formatée indiquant les noms d'utilisateur et les identifiants de tous les utilisateurs de la zone.

🏛️ Gestion des domaines

list-realms

Récupère tous les domaines disponibles dans l'instance Keycloak.

Paramètres : Aucun requis

Exemple d'utilisation :

{}

Réponse : Renvoie une liste de tous les noms de domaines disponibles dans l'installation de Keycloak.

Cas d'utilisation :

• Découverte des domaines disponibles
• Validation des noms de domaines avant d'autres opérations
• Aperçu administratif de l'installation de Keycloak

🔐 Gestion des rôles

list-roles

Liste tous les rôles définis pour un client spécifique au sein d'un royaume. Utile pour comprendre les autorisations et les rôles disponibles avant de les attribuer.

Paramètres requis :

• realm (chaîne) : Nom de la zone cible
• clientId (chaîne) : ID du client ou UUID du client cible

Exemple d'utilisation :

{"realm" : "my-app-realm", "clientId" : "my-application" }

Alternative avec l'UUID du client :

{ "realm" : "my-app-realm", "clientId" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Réponse : Renvoie une liste formatée de tous les noms de rôle disponibles pour le client spécifié.

💡 Conseil : vous pouvez utiliser l'identifiant lisible par l'homme du client ou son identifiant UUID.

update-user-roles

Gère les attributions de rôles client pour un utilisateur. Permet à la fois d'ajouter et de supprimer des rôles en une seule opération.

Paramètres requis :

• realm (chaîne) : Nom du domaine cible
• userId (chaîne) : Identifiant unique de l'utilisateur
• clientId (chaîne) : ID du client ou UUID

Paramètres optionnels :

• rolesToAdd (array) : Liste des noms de rôles à attribuer à l'utilisateur
• rolesToRemove (tableau) : Liste des noms de rôles à retirer à l'utilisateur

Exemple d'utilisation - Ajout de rôles :

{ "realm" : "my-app-realm", "userId" : "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c", "clientId" : "my-application", "rolesToAdd" : ["admin", "user-manager", "report-viewer"] } }

Exemple d'utilisation - Suppression de rôles :

{ "realm" : "my-app-realm", "userId" : "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c", "clientId" : "my-application", "rolesToRemove" : ["temporary-access", "beta-tester"] }

Exemple d'utilisation - Opération combinée :

{ "realm" : "my-app-realm", "userId" : "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c", "clientId" : "my-application", "rolesToAdd" : ["senior-user"], "rolesToRemove" : ["junior-user", "trainee"] }

Réponse : Résumé détaillé des rôles ajoutés, supprimés et des éventuelles erreurs rencontrées.

🔍 Notes :

• Au moins un des rôlesToAdd ou rolesToRemove doit être fourni
• Les rôles inexistants sont ignorés avec des avertissements
• L'opération est atomique par liste de rôles (tous ou aucun pour chaque type d'opération)

🚀 Conseils d'utilisation

1. Identifiants et noms d'utilisateur: La plupart des opérations nécessitent des identifiants d'utilisateur (UUID), et non des noms d'utilisateur. Utilisez list-users pour trouver l'ID utilisateur correct.

2. Identification du client: Le paramètre clientId accepte à la fois les identifiants client lisibles par l'homme et les identifiants UUID.

3. Validation du domaine: Vérifiez toujours les noms de domaines à l'aide de list-realms avant d'effectuer des opérations.

4. Découverte des rôles: Utilisez list-roles pour découvrir les rôles disponibles avant de tenter d'attribuer des rôles.

5. Gestion des erreurs: Tous les outils fournissent des messages d'erreur détaillés permettant de résoudre les problèmes d'authentification, d'autorisation ou de paramètres.

Développement

Configuration de l'environnement de développement

# Cloner le dépôt git clone <repository-url> # Installer les dépendances npm install # Démarrer le serveur de développement avec le mode watch npm run watch

Ajouter de nouveaux outils

Pour ajouter un nouvel outil au serveur :

1. Définir le schéma de l'outil dans src/index.ts en utilisant Zod
2. Ajouter la définition de l'outil au gestionnaire ListToolsRequestSchema
3. Implémenter le gestionnaire d'outils dans l'instruction de commutation CallToolRequestSchema
4. Mettre à jour ce README pour documenter le nouvel outil

Test

Utilisation de l'inspecteur MCP

L'inspecteur MCP est un excellent outil pour tester votre serveur MCP :

npx -y @modelcontextprotocol/inspector npx -y @octodet/keycloak-mcp

Tests d'intégration

Pour tester une instance locale de Keycloak :

# Démarrer Keycloak avec Docker docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev # Dans un autre terminal, lancer le serveur MCP npm run build node build/index.js

Déploiement

Paquet NPM

Ce projet est publié sur NPM sous @octodet/keycloak-mcp.

Déploiement automatisé

Ce projet utilise GitHub Actions for CI/CD pour tester et publier automatiquement vers NPM lorsqu'une nouvelle version est créée.

Prérequis

• Node.js 18 ou supérieur
• Instance de Keycloak en cours d'exécution

Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

Auteur

Octodet - Construire des outils intelligents pour les développeurs