entraadm-mcp

Englisch | 日本語

MCP-Server für die Sichtung von Microsoft-Entra-ID-Anmelde- und Überwachungsprotokollen. Nur lesend.

Warum dies statt des offiziellen Microsoft MCP Server for Enterprise

Microsoft bietet einen offiziellen MCP Server for Enterprise für Entra-ID-Daten an. Er eignet sich gut für einen interaktiven Administrator an der Tastatur, ist jedoch nicht für einen unbeaufsichtigten Triage-Bot geeignet:

• Nur delegierte Authentifizierung. Der offizielle Server unterstützt keine App-only-Authentifizierung (Client-Anmeldeinformationen), daher kann er nicht unbeaufsichtigt hinter einem Dienstkonto ausgeführt werden. entraadm-mcp ist für diesen Fall gebaut: App-only in Produktion, mit einem delegierten (az login) Fallback für die lokale Entwicklung.

• Ein allgemeines Graph-Abfragetool, kein festes Toolset. Der offizielle Server stellt ein Tool bereit, mit dem das Modell beliebige GET-/Schema-Erkennungsaufrufe an Microsoft Graph konstruieren kann. Das ist für einen Menschen flexibel, aber schwierig hinter eine Zulassungsliste für ein automatisiertes Triage- Profil zu setzen. entraadm-mcp stellt stattdessen sieben feste, schreibgeschützte Tools bereit.

• Keine AADSTS-Übersetzung. Anmeldefehler kommen als rohe Fehlercodes zurück; die Triage benötigt dennoch eine Nachschlagetabelle. entraadm-mcp kommentiert jeden Anmeldefehler mit der tatsächlichen Bedeutung des Codes.

• Keine anfrageübergreifende Aggregation. Microsoft Graph selbst kann Anmeldungen nicht serverseitig nach status/errorCode filtern und hat keine eingebaute Passwort-Spray-Ansicht. signin_failure_stats aggregiert clientseitig und kennzeichnet IPs mit fehlgeschlagenen Anmeldungen gegen viele verschiedene Benutzer – das Muster, das Entras pro-Konto intelligente Sperre nicht von selbst erkennt.

Related MCP server: Microsoft Graph MCP Server

Tools

Jedes Tool ist schreibgeschützt. Schreiboperationen (Entsperren eines Kontos, Zurücksetzen eines Passworts, Widerrufen einer Sitzung) liegen außerhalb des Anwendungsbereichs dieses Servers.

Authentifizierungsmodell

Zwei Authentifizierungsmodi, ausgewählt durch die gesetzten Umgebungsvariablen:

Das Setzen von einer oder zwei der drei App-only-Variablen ist ein Konfigurationsfehler und der Server weigert sich zu starten, anstatt stillschweigend auf einen anderen Authentifizierungsmodus als beabsichtigt zurückzufallen.

Erforderliche Graph-Berechtigungen

Eine fehlende Berechtigung bringt ein Tool nie zum Absturz. Es degradiert dieses Tool (oder dieses eine Feld) zu {"error": "...", "missing_permission": "..."} mit einer menschenlesbaren Erklärung, welche Rolle oder Berechtigung benötigt wird, sodass health_check und alle anderen Tools auch vor der Erteilung vollständiger Berechtigungen nutzbar bleiben.

Setup

uv tool install entraadm-mcp
# or
pip install entraadm-mcp

Konfiguration

Setzen Sie die drei App-only-Variablen für Produktions-/unbeaufsichtigten Einsatz:

export ENTRAADM_TENANT_ID=00000000-0000-0000-0000-000000000000
export ENTRAADM_CLIENT_ID=00000000-0000-0000-0000-000000000000
export ENTRAADM_CLIENT_SECRET=your-client-secret

Oder lassen Sie alle drei ungesetzt und führen Sie zuerst az login für die lokale Entwicklung aus.

Optional:

# Default page cap for the log-scanning tools (1-50, default 5).
export ENTRAADM_MAX_PAGES_DEFAULT=5

Verwendung

Claude Code (Plugin)

/plugin marketplace add shigechika/entraadm-mcp
/plugin install entraadm-mcp@entraadm-mcp

Claude Code (manuell)

Fügen Sie zu .mcp.json hinzu:

{
  "mcpServers": {
    "entraadm-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["entraadm-mcp"],
      "env": {
        "ENTRAADM_TENANT_ID": "${ENTRAADM_TENANT_ID:-}",
        "ENTRAADM_CLIENT_ID": "${ENTRAADM_CLIENT_ID:-}",
        "ENTRAADM_CLIENT_SECRET": "${ENTRAADM_CLIENT_SECRET:-}"
      }
    }
  }
}

Direkte Ausführung

entraadm-mcp

CLI-Optionen

Hinweise

• Abdeckungsvertrag. Jedes Ergebnis, das eine paginierte Graph-Sammlung durchläuft, trägt ein capped-Boolesches Feld, wenn sein Fenster nicht vollständig gescannt wurde – ein teilweiser Scan wird nie als vollständig gemeldet.

• found: false ist kein Fehler. get_user und get_user_auth_methods antworten auf ein nicht vorhandenes Konto mit {"found": false, ...}, nicht mit einem error- Schlüssel – ein falsch geschriebener userPrincipalName sollte niemals wie ein defekter Server aussehen.

• Aufbewahrung. Entra ID P1 speichert Anmelde- und Verzeichnis-Überwachungsprotokolle für 30 Tage. Ein Fenster darüber hinaus gibt ein leeres Ergebnis zurück, keinen Fehler.

Entwicklung

uv sync --dev
uv run pytest -v
uv run ruff check .
uv run ruff format --check .

Live-Smoke-Test

uv run python scripts/smoke_test.py

Nur lesend, keine Nutzlasten werden ausgegeben (nur Toolnamen/Status/Zeilenanzahlen), und begrenzt (kleine explizite Fenster/Seitengrenzen) – nichts hier schreibt in den Mandanten oder scannt mehr als einen Tag Protokolle.

Veröffentlichung

Dieses Repository verwendet release-please gesteuert von Conventional Commits. Mergen Sie einen feat:/fix:-PR in main, und release-please öffnet (oder aktualisiert) einen Release-PR; das Mergen dieses PRs taggt ein Release und löst die Veröffentlichungspipeline aus (PyPI, MCP Registry).

Lizenz

MIT