Serveur EntraID MCP (Microsoft Graph FastMCP)

Ce projet fournit un serveur FastMCP modulaire et orienté ressources pour interagir avec l'API Microsoft Graph. Il est conçu pour l'extensibilité, la maintenabilité et la sécurité, et prend en charge les requêtes avancées pour les utilisateurs, les journaux de connexion, l'état MFA et les utilisateurs privilégiés.

Caractéristiques

• Structure modulaire des ressources
  • Chaque ressource (utilisateurs, journaux de connexion, MFA, etc.) est implémentée dans son propre module sous src/msgraph_mcp_server/resources/.
  • Facile à étendre avec de nouvelles ressources (par exemple, des groupes, des appareils).
• Client graphique centralisé
  • Gère l'authentification et l'initialisation du client.
  • Il est partagé par tous les modules de ressources.
• Opérations complètes sur les utilisateurs
  • Recherche d'utilisateurs par nom/email.
  • Recherche d'un utilisateur par son identifiant.
  • Liste de tous les utilisateurs privilégiés (membres de l'annuaire).
• Gestion complète du cycle de vie des groupes et des membres
  • Création, lecture, mise à jour et suppression de groupes.
  • Ajout/suppression de membres et de propriétaires de groupes.
  • Recherche et énumération des groupes et de leurs membres.
• Gestion des applications et des services principaux
  • Lister, créer, mettre à jour et supprimer des applications (enregistrements d'applications).
  • Liste, création, mise à jour et suppression des principaux services.
  • Visualiser les attributions de rôles et les autorisations déléguées pour les applications et les services principaux.
• Opérations sur les journaux de connexion
  • Interroger les journaux de connexion d'un utilisateur pour les X derniers jours.
• Opérations MFA
  • Obtenir le statut MFA d'un utilisateur.
  • Obtenir le statut MFA pour tous les membres d'un groupe.
• Gestion des mots de passe
  • Réinitialiser les mots de passe des utilisateurs directement avec des mots de passe sécurisés personnalisés ou générés automatiquement.
  • Possibilité d'exiger un changement de mot de passe lors de la prochaine connexion.
• Aide aux autorisations
  • Suggère les autorisations Microsoft Graph appropriées pour les tâches courantes.
  • Recherche et exploration des autorisations Graph disponibles.
  • Aide à mettre en œuvre le principe du moindre privilège en ne recommandant que les autorisations nécessaires.
• Gestion des erreurs et journalisation
  • Gestion cohérente des erreurs et rapports de progression via le contexte FastMCP.
  • Journalisation détaillée pour le dépannage.
• Sécurité
  • les fichiers.env et secret sont exclus du contrôle de version.
  • Utilise les meilleures pratiques de Microsoft pour l'authentification.

Structure du projet

src/msgraph_mcp_server/ ├── auth/ # Logique d'authentification (GraphAuthManager) ├── ressources/ # Modules de ressources (users, signin_logs, mfa, ...) │ ├── users.py # Opérations sur les utilisateurs (recherche, obtention par ID, etc.) │ ├── signin_logs.py # Opérations sur les journaux de connexion │ ├── mfa.py # MFA status operations │ ├── permissions_helper.py # Graph permissions utilities and suggestions │ ├── applications.py # Application (app registration) operations │ ├── service_principals.py # Service principal operations │ └── ...                 # Autres modules de ressources ├── utils/ # Core GraphClient et autres outils ultilities, tels que le générateur de mot de passe... ├── server.py # Point d'entrée du serveur FastMCP (enregistre les outils/ressources) ├── __init__.py # Marqueur de paquetage

Utilisation

1. Mise en place

• Cloner le repo.
• Créez un fichier config/.env avec vos identifiants Azure AD :

  TENANT_ID=votre-tenant-id CLIENT_ID=votre-client-id CLIENT_SECRET=votre-client-secret

• (Facultatif) Configurez l'authentification par certificat si nécessaire.

2. Test et développement

Vous pouvez tester et développer votre serveur MCP directement en utilisant le CLI FastMCP :

fastmcp dev '/path/to/src/msgraph_mcp_server/server.py'

Ceci lance un environnement de développement interactif avec l'inspecteur MCP. Pour plus d'informations et une utilisation avancée, voir la documentation FastMCP.

3. Outils disponibles

Outils pour les utilisateurs

• search_users(query, ctx, limit=10) - Recherche d'utilisateurs par nom/email
• get_user_by_id(user_id, ctx) - Obtenir les détails de l'utilisateur par ID
• get_privileged_users(ctx) - Liste tous les utilisateurs ayant un rôle privilégié dans l'annuaire
• get_user_roles(user_id, ctx) - Affiche tous les rôles attribués à un utilisateur dans l'annuaire
• get_user_groups(user_id, ctx) - Affiche tous les groupes (y compris les appartenances transitives) d'un utilisateur

Outils de groupe

• get_all_groups(ctx, limit=100) - Récupère tous les groupes (avec pagination)
• get_group_by_id(group_id, ctx) - Obtient un groupe spécifique par son ID
• search_groups_by_name(name, ctx, limit=50) - Recherche les groupes par leur nom d'affichage
• get_group_members(group_id, ctx, limit=100) - Permet d'obtenir les membres d'un groupe par leur identifiant
• create_group(ctx, group_data) - Crée un nouveau groupe (voir ci-dessous pour les champs group_data)
• update_group(group_id, ctx, group_data) - Met à jour un groupe existant (champs : displayName, mailNickname, description, visibility)
• delete_group(group_id, ctx) - Supprime un groupe par son ID
• add_group_member(group_id, member_id, ctx) - Ajoute un membre (utilisateur, groupe, appareil, etc.) à un groupe
• remove_group_member(group_id, member_id, ctx) - Supprime un membre d'un groupe
• add_group_owner(group_id, owner_id, ctx) - Ajoute un propriétaire à un groupe
• remove_group_owner(group_id, owner_id, ctx) - Supprime un propriétaire d'un groupe

Exemple de création/mise à jour de groupe :

• group_data pour create_group et update_group doit être un dictionnaire avec des clés telles que
  • displayName (obligatoire pour la création)
  • mailNickname (obligatoire pour la création)
  • description (facultatif)
  • groupTypes (facultatif, par exemple ["Unified"])
  • mailEnabled (facultatif)
  • securityEnabled (facultatif)
  • visibility (facultatif, "Private" ou "Public")
  • owners (facultatif, liste d'ID d'utilisateurs)
  • members (facultatif, liste d'identifiants)
  • membershipRule (obligatoire pour les groupes dynamiques)
  • membershipRuleProcessingState (facultatif, "On" ou "Paused")

Voir la documentation de groups.py pour plus de détails sur les champs et les comportements supportés.

Outils d'enregistrement des connexions

• get_user_sign_ins(user_id, ctx, days=7) - Récupère les logs de connexion d'un utilisateur

Outils MFA

• get_user_mfa_status(user_id, ctx) - Obtenir le statut MFA d'un utilisateur
• get_group_mfa_status(group_id, ctx) - Obtenir l'état de l'AFM pour tous les membres d'un groupe

Outils pour les appareils

• get_all_managed_devices(filter_os=None) - Obtient tous les périphériques gérés (filtre optionnel par OS)
• get_managed_devices_by_user(user_id) - Permet d'obtenir tous les périphériques gérés pour un utilisateur spécifique

Outils de politique d'accès conditionnel

• get_conditional_access_policies(ctx) - Récupère toutes les politiques d'accès conditionnel
• get_conditional_access_policy_by_id(policy_id, ctx) - Permet d'obtenir une seule politique d'accès conditionnel par son identifiant

Outils de journal d'audit

• get_user_audit_logs(user_id, days=30) - Permet d'obtenir tous les journaux d'audit de répertoire pertinents pour un utilisateur par user_id au cours des N derniers jours

Outils de gestion des mots de passe

• reset_user_password_direct(user_id, password=None, require_change_on_next_signin=True, generate_password=False, password_length=12) - Réinitialise le mot de passe d'un utilisateur avec une valeur de mot de passe spécifique ou génère un mot de passe aléatoire sécurisé

Outils d'aide aux permissions

• suggest_permissions_for_task(task_category, task_name) - Suggère des autorisations Microsoft Graph pour une tâche spécifique sur la base de correspondances communes
• list_permission_categories_and_tasks() - Liste toutes les catégories et tâches disponibles pour les suggestions de permissions
• get_all_graph_permissions() - Obtenir toutes les autorisations Microsoft Graph directement à partir de l'API Microsoft Graph
• search_permissions(search_term, permission_type=None) - Recherche de permissions Microsoft Graph par mot-clé

Outils d'application

• list_applications(ctx, limit=100) - Liste toutes les applications (enregistrements d'applications) dans le locataire, avec pagination
• get_application_by_id(app_id, ctx) - Permet d'obtenir une application spécifique par son ID d'objet (y compris les attributions de rôles d'application et les autorisations déléguées)
• create_application(ctx, app_data) - Créer une nouvelle application (voir ci-dessous pour les champs app_data)
• update_application(app_id, ctx, app_data) - Met à jour une application existante (champs : displayName, signInAudience, tags, identifierUris, web, api, requiredResourceAccess)
• delete_application(app_id, ctx) - Supprime une application en fonction de son identifiant

Création/mise à jour d'une application Exemple :

• app_data pour create_application et update_application devrait être un dictionnaire avec des clés telles que
  • displayName (obligatoire pour la création)
  • signInAudience (facultatif)
  • tags (optionnel)
  • identifierUris (facultatif)
  • web (optionnel)
  • api (facultatif)
  • requiredResourceAccess (facultatif)

Outils pour les directeurs de service

• list_service_principals(ctx, limit=100) - Liste tous les principaux de service du locataire, avec pagination
• get_service_principal_by_id(sp_id, ctx) - Permet d'obtenir un principal de service spécifique par son ID d'objet (y compris les affectations de rôles d'application et les autorisations déléguées)
• create_service_principal(ctx, sp_data) - Créer un nouveau principal de service (voir ci-dessous pour les champs sp_data)
• update_service_principal(sp_id, ctx, sp_data) - Met à jour un service principal existant (champs : displayName, accountEnabled, tags, appRoleAssignmentRequired)
• delete_service_principal(sp_id, ctx) - Supprime un principal de service par son ID d'objet

Création/mise à jour d'un principal de service Exemple :

• sp_data pour create_service_principal et update_service_principal devrait être un dictionnaire avec des clés telles que
  • appId (obligatoire pour la création)
  • accountEnabled (optionnel)
  • tags (facultatif)
  • appRoleAssignmentRequired (facultatif)
  • displayName (optionnel)

Exemple de ressource

• greeting://{nom} - Renvoie un message d'accueil personnalisé

Extension du serveur

• Ajouter de nouveaux modules de ressources sous resources/ (par exemple, groups.py, devices.py).
• Enregistrer de nouveaux outils dans server.py en utilisant le décorateur FastMCP @mcp.tool().
• Utiliser le GraphClient partagé pour tous les appels d'API.

Sécurité et bonnes pratiques

• Ne jamais livrer de secrets : les fichiers .env et autres fichiers sensibles sont gitignotés.
• Utiliser le moindre privilège : N'accordez que les autorisations Microsoft Graph nécessaires à votre application Azure AD.
• Auditer et surveiller : Utilisez la sortie de la journalisation pour le dépannage et la surveillance.

Autorisations requises pour l'API Graph

Remarque :Group.ReadWrite.All est nécessaire pour la création, la mise à jour et la suppression de groupes, ainsi que pour l'ajout/la suppression de membres ou de propriétaires de groupes. Group.Read.All et GroupMember.Read.All sont suffisants pour les requêtes en lecture seule sur les groupes et les membres.

Avancé : Utilisation avec Claude ou Cursor

Utilisation de Claude (Anthropic)

Pour installer et exécuter ce serveur en tant qu'outil Claude MCP, utilisez :

fastmcp install '/path/to/src/msgraph_mcp_server/server.py' \N --with msgraph-sdk --with azure-identity --with azure-core --with msgraph-core \N -f /path/to/.env

• Remplacez /path/to/ par le chemin de votre projet.
• Le drapeau -f pointe vers votre fichier .env (ne jamais livrer de secrets !).

Utilisation avec Cursor

Ajoutez ce qui suit à votre fichier .cursor/mcp.json (n'incluez pas les secrets réels dans le contrôle de version) :

{ "EntraID MCP Server" : {"command" : "uv", "args" : [ "run", "--with", "azure-core", "--with", "azure-identity", "--with", "fastmcp", "--with", "msgraph-core", "--with", "msgraph-sdk", "fastmcp", "run", "/path/to/src/msgraph_mcp_server/server.py" ], "env" : { "TENANT_ID" : "<votre-identifiant-tenant>", "CLIENT_ID" : "<votre-identifiant-client>", "CLIENT_SECRET" : "<votre-secret-client>" } } }

• Remplacez /path/to/ et les variables d'environnement par vos valeurs réelles.
• Ne livrez jamais de vrais secrets à votre dépôt !

Licence

MIT