EntraID MCP Server

EntraID MCP-Server (Microsoft Graph FastMCP)

Dieses Projekt bietet einen modularen, ressourcenorientierten FastMCP-Server für die Interaktion mit der Microsoft Graph-API. Es ist auf Erweiterbarkeit, Wartung und Sicherheit ausgelegt und unterstützt erweiterte Abfragen für Benutzer, Anmeldeprotokolle, MFA-Status und privilegierte Benutzer.

Merkmale

• Modulare Ressourcenstruktur:
  • Jede Ressource (Benutzer, Anmeldeprotokolle, MFA usw.) wird in einem eigenen Modul unter src/msgraph_mcp_server/resources/ implementiert.
  • Einfache Erweiterung mit neuen Ressourcen (z. B. Gruppen, Geräten).
• Zentralisierter Graph-Client:
  • Behandelt die Authentifizierung und Client-Initialisierung.
  • Von allen Ressourcenmodulen gemeinsam genutzt.
• Umfassende Benutzervorgänge:
  • Suchen Sie Benutzer nach Name/E-Mail.
  • Benutzer nach ID abrufen.
  • Listen Sie alle privilegierten Benutzer (Mitglieder der Verzeichnisrolle) auf.
• Vollständiges Gruppenlebenszyklus- und Mitgliedschaftsmanagement:
  • Gruppen erstellen, lesen, aktualisieren und löschen.
  • Gruppenmitglieder und Besitzer hinzufügen/entfernen.
  • Suchen und Auflisten von Gruppen und Gruppenmitgliedern.
• Anwendungs- und Service-Principal-Management:
  • Auflisten, Erstellen, Aktualisieren und Löschen von Anwendungen (App-Registrierungen).
  • Auflisten, Erstellen, Aktualisieren und Löschen von Dienstprinzipalen.
  • Zeigen Sie App-Rollenzuweisungen und delegierte Berechtigungen für Anwendungen und Dienstprinzipale an.
• Anmeldeprotokollvorgänge:
  • Abfrage der Anmeldeprotokolle für einen Benutzer für die letzten X Tage.
• MFA-Operationen:
  • Holen Sie sich den MFA-Status für einen Benutzer.
  • Erhalten Sie den MFA-Status für alle Mitglieder einer Gruppe.
• Passwortverwaltung:
  • Setzen Sie Benutzerkennwörter direkt mit benutzerdefinierten oder automatisch generierten sicheren Kennwörtern zurück.
  • Option, bei der nächsten Anmeldung eine Kennwortänderung anzufordern.
• Berechtigungshelfer:
  • Schlagen Sie geeignete Microsoft Graph-Berechtigungen für allgemeine Aufgaben vor.
  • Suchen und erkunden Sie verfügbare Graph-Berechtigungen.
  • Hilft bei der Umsetzung des Prinzips der geringsten Privilegien, indem nur notwendige Berechtigungen empfohlen werden.
• Fehlerbehandlung und -protokollierung:
  • Konsistente Fehlerbehandlung und Fortschrittsberichterstattung über den FastMCP-Kontext.
  • Detaillierte Protokollierung zur Fehlerbehebung.
• Sicherheit:
  • .env und geheime Dateien sind von der Versionskontrolle ausgeschlossen.
  • Verwendet bewährte Methoden von Microsoft zur Authentifizierung.

Projektstruktur

Verwendung

1. Einrichtung

• Klonen Sie das Repo.
• Erstellen Sie eine config/.env Datei mit Ihren Azure AD-Anmeldeinformationen:
  TENANT_ID=your-tenant-id CLIENT_ID=your-client-id CLIENT_SECRET=your-client-secret
• (Optional) Richten Sie bei Bedarf eine zertifikatsbasierte Authentifizierung ein.

2. Testen und Entwickeln

Sie können Ihren MCP-Server direkt mit der FastMCP-CLI testen und entwickeln:

Dadurch wird eine interaktive Entwicklungsumgebung mit dem MCP Inspector gestartet. Weitere Informationen und erweiterte Nutzungsmöglichkeiten finden Sie in der FastMCP-Dokumentation .

3. Verfügbare Tools

Benutzertools

• search_users(query, ctx, limit=10) — Benutzer nach Name/E-Mail suchen
• get_user_by_id(user_id, ctx) — Benutzerdetails nach ID abrufen
• get_privileged_users(ctx) — Listet alle Benutzer in privilegierten Verzeichnisrollen auf
• get_user_roles(user_id, ctx) — Alle einem Benutzer zugewiesenen Verzeichnisrollen abrufen
• get_user_groups(user_id, ctx) — Alle Gruppen (einschließlich transitiver Mitgliedschaften) für einen Benutzer abrufen

Gruppentools

• get_all_groups(ctx, limit=100) — Alle Gruppen abrufen (mit Paging)
• get_group_by_id(group_id, ctx) — Ruft eine bestimmte Gruppe anhand ihrer ID ab
• search_groups_by_name(name, ctx, limit=50) — Suche nach Gruppen nach Anzeigenamen
• get_group_members(group_id, ctx, limit=100) — Mitglieder einer Gruppe nach Gruppen-ID abrufen
• create_group(ctx, group_data) — Erstellt eine neue Gruppe (siehe unten für group_data-Felder)
• update_group(group_id, ctx, group_data) — Aktualisieren einer vorhandenen Gruppe (Felder: displayName, mailNickname, Beschreibung, Sichtbarkeit)
• delete_group(group_id, ctx) — Löscht eine Gruppe anhand ihrer ID
• add_group_member(group_id, member_id, ctx) — Ein Mitglied (Benutzer, Gruppe, Gerät usw.) zu einer Gruppe hinzufügen
• remove_group_member(group_id, member_id, ctx) — Entfernt ein Mitglied aus einer Gruppe
• add_group_owner(group_id, owner_id, ctx) — Einen Besitzer zu einer Gruppe hinzufügen
• remove_group_owner(group_id, owner_id, ctx) — Einen Besitzer aus einer Gruppe entfernen

Beispiel für die Gruppenerstellung/-aktualisierung:

• group_data für create_group und update_group sollte ein Wörterbuch mit Schlüsseln wie den folgenden sein:
  • displayName (erforderlich zum Erstellen)
  • mailNickname (erforderlich zum Erstellen)
  • description (optional)
  • groupTypes (optional, zB ["Unified"] )
  • mailEnabled (optional)
  • securityEnabled (optional)
  • visibility (optional, „Privat“ oder „Öffentlich“)
  • owners (optional, Liste der Benutzer-IDs)
  • members (optional, Liste der IDs)
  • membershipRule (erforderlich für dynamische Gruppen)
  • membershipRuleProcessingState (optional, „Ein“ oder „Pausiert“)

Weitere Einzelheiten zu unterstützten Feldern und Verhaltensweisen finden Sie in den groups.py Dokumentationszeichenfolgen.

Tools für das Anmeldeprotokoll

• get_user_sign_ins(user_id, ctx, days=7) — Anmeldeprotokolle für einen Benutzer abrufen

MFA-Tools

• get_user_mfa_status(user_id, ctx) — MFA-Status für einen Benutzer abrufen
• get_group_mfa_status(group_id, ctx) — MFA-Status für alle Gruppenmitglieder abrufen

Gerätetools

• get_all_managed_devices(filter_os=None) — Alle verwalteten Geräte abrufen (optional nach Betriebssystem filtern)
• get_managed_devices_by_user(user_id) — Alle verwalteten Geräte für einen bestimmten Benutzer abrufen

Tools für Richtlinien für bedingten Zugriff

• get_conditional_access_policies(ctx) — Alle Richtlinien für bedingten Zugriff abrufen
• get_conditional_access_policy_by_id(policy_id, ctx) — Ruft eine einzelne bedingte Zugriffsrichtlinie anhand ihrer ID ab

Prüfprotokoll-Tools

• get_user_audit_logs(user_id, days=30) — Ruft alle relevanten Verzeichnis-Audit-Protokolle für einen Benutzer nach Benutzer-ID innerhalb der letzten N Tage ab

Tools zur Kennwortverwaltung

• reset_user_password_direct(user_id, password=None, require_change_on_next_sign_in=True, generate_password=False, password_length=12) — Setzt das Passwort eines Benutzers mit einem bestimmten Passwortwert zurück oder generiert ein sicheres, zufälliges Passwort

Hilfstools für Berechtigungen

• suggest_permissions_for_task(task_category, task_name) – Schlagen Sie Microsoft Graph-Berechtigungen für eine bestimmte Aufgabe basierend auf allgemeinen Zuordnungen vor.
• list_permission_categories_and_tasks() — Listet alle verfügbaren Kategorien und Aufgaben für Berechtigungsvorschläge auf
• get_all_graph_permissions() – Alle Microsoft Graph-Berechtigungen direkt von der Microsoft Graph-API abrufen
• search_permissions(search_term, permission_type=None) – Suche nach Microsoft Graph-Berechtigungen nach Stichwort

Anwendungstools

• list_applications(ctx, limit=100) — Listet alle Anwendungen (App-Registrierungen) im Mandanten auf, mit Paging
• get_application_by_id(app_id, ctx) – Ruft eine bestimmte Anwendung anhand ihrer Objekt-ID ab (einschließlich App-Rollenzuweisungen und delegierter Berechtigungen).
• create_application(ctx, app_data) — Erstellt eine neue Anwendung (siehe unten für app_data-Felder)
• update_application(app_id, ctx, app_data) – Aktualisieren Sie eine vorhandene Anwendung (Felder: displayName, signInAudience, Tags, identifierUris, web, api, requiredResourceAccess)
• delete_application(app_id, ctx) — Löscht eine Anwendung anhand ihrer Objekt-ID

Beispiel für die Erstellung/Aktualisierung einer Anwendung:

• app_data für create_application und update_application sollte ein Wörterbuch mit Schlüsseln wie den folgenden sein:
  • displayName (erforderlich zum Erstellen)
  • signInAudience (optional)
  • tags (optional)
  • identifierUris (optional)
  • web (optional)
  • api (optional)
  • requiredResourceAccess (optional)

Dienstprinzipaltools

• list_service_principals(ctx, limit=100) — Listet alle Dienstprinzipale im Mandanten auf, mit Seitennummerierung
• get_service_principal_by_id(sp_id, ctx) – Ruft einen bestimmten Dienstprinzipal über seine Objekt-ID ab (einschließlich App-Rollenzuweisungen und delegierter Berechtigungen).
• create_service_principal(ctx, sp_data) — Einen neuen Dienstprinzipal erstellen (siehe unten für sp_data-Felder)
• update_service_principal(sp_id, ctx, sp_data) – Aktualisieren Sie einen vorhandenen Dienstprinzipal (Felder: displayName, accountEnabled, tags, appRoleAssignmentRequired)
• delete_service_principal(sp_id, ctx) — Löscht einen Dienstprinzipal anhand seiner Objekt-ID

Beispiel für die Erstellung/Aktualisierung von Dienstprinzipalen:

• sp_data für create_service_principal und update_service_principal sollte ein Wörterbuch mit Schlüsseln wie den folgenden sein:
  • appId (zum Erstellen erforderlich)
  • accountEnabled (optional)
  • tags (optional)
  • appRoleAssignmentRequired (optional)
  • displayName (optional)

Beispielressource

• greeting://{name} — Gibt eine personalisierte Begrüßung zurück

Erweiterung des Servers

• Fügen Sie unter resources/ neue Ressourcenmodule hinzu (z. B. groups.py , devices.py ).
• Registrieren Sie neue Tools in server.py mit dem FastMCP @mcp.tool() -Dekorator.
• Verwenden Sie den gemeinsam genutzten GraphClient für alle API-Aufrufe.

Sicherheit und bewährte Methoden

• Geben Sie niemals Geheimnisse preis: .env und andere sensible Dateien werden bei Git ignoriert.
• Verwenden Sie das Prinzip der geringsten Berechtigungen: Erteilen Sie Ihrer Azure AD-App nur die erforderlichen Microsoft Graph-Berechtigungen.
• Prüfen und Überwachen: Verwenden Sie die Protokollausgabe zur Fehlerbehebung und Überwachung.

Erforderliche Graph-API-Berechtigungen

Hinweis: Group.ReadWrite.All ist zum Erstellen, Aktualisieren und Löschen von Gruppen sowie zum Hinzufügen/Entfernen von Gruppenmitgliedern oder -besitzern erforderlich. Group.Read.All und GroupMember.Read.All reichen für schreibgeschützte Gruppen- und Mitgliedschaftsabfragen aus.

Erweitert: Verwendung mit Claude oder Cursor

Verwendung mit Claude (Anthropisch)

Um diesen Server als Claude MCP-Tool zu installieren und auszuführen, verwenden Sie:

• Ersetzen Sie /path/to/ durch Ihren tatsächlichen Projektpfad.
• Das Flag -f verweist auf Ihre .env Datei (geben Sie niemals Geheimnisse preis!).

Verwendung mit Cursor

Fügen Sie Folgendes zu Ihrer .cursor/mcp.json hinzu (schließen Sie keine tatsächlichen Geheimnisse in die Versionskontrolle ein):

• Ersetzen Sie /path/to/ und die Umgebungsvariablen durch Ihre tatsächlichen Werte.
• Übergeben Sie Ihrem Repository niemals echte Geheimnisse!

Lizenz

MIT