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.

Related MCP server: ms-365-admin-mcp-server

Projektstruktur

src/msgraph_mcp_server/
├── auth/           # Authentication logic (GraphAuthManager)
├── resources/      # Resource modules (users, signin_logs, mfa, ...)
│   ├── users.py            # User operations (search, get by ID, etc.)
│   ├── signin_logs.py      # Sign-in log operations
│   ├── 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
│   └── ...                 # Other resource modules
├── utils/          # Core GraphClient and other ultilities tool, such as password generator..
├── server.py       # FastMCP server entry point (registers tools/resources)
├── __init__.py     # Package marker

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:

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

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:

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

• 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):

{
  "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": "<your-tenant-id>",
      "CLIENT_ID": "<your-client-id>",
      "CLIENT_SECRET": "<your-client-secret>"
    }
  }
}

• Ersetzen Sie /path/to/ und die Umgebungsvariablen durch Ihre tatsächlichen Werte.

• Übergeben Sie Ihrem Repository niemals echte Geheimnisse!

Lizenz

MIT