Google Workspace Directory MCP

Produktionsorientierter, schreibgeschützter MCP-Dienst für eng abgegrenzte Google-Workspace-Benutzersuchen. Er verwendet Python, FastMCP Streamable HTTP, die Google Admin SDK Directory API, eine dedizierte Service-Account-JSON-Anmeldedaten, Domain-weite Delegierung (DWD) und einen festen, delegierten Admin-Betreff aus der Serverkonfiguration.

Der Dienst führt ausschließlich users.get und users.list aus. Er kann keine Benutzer anlegen, aktualisieren, sperren, archivieren, umbenennen, löschen oder anderweitig verändern.

Architektur und Bedrohungsgrenze

MCP client
  -> external TLS and human authentication at Nginx Proxy Manager
    -> dedicated ingress network + gateway secret and verified identity headers
      -> FastMCP /mcp on 0.0.0.0:8000
        -> fixed-subject DWD credential provider
          -> Google Admin SDK Directory API (read-only users scope)

Das externe Gateway authentifiziert den Menschen und muss ein gemeinsames Gateway-Geheimnis sowie eine verifizierte Aufruferidentität injizieren. Die Anwendung überprüft beides, autorisiert die Identität und nimmt sie zusammen mit einer generierten Anforderungs-ID in jedes Tool-Auditereignis auf. Das gemeinsame Geheimnis beweist, dass die Anforderung über den vertrauenswürdigen Eingangspfad kam; es identifiziert keine Einzelperson und ersetzt keine Netzwerkisolierung oder externes TLS. NPM muss vom Client gelieferte Kopien beider Header entfernen, bevor es eigene Werte injiziert.

Die Anwendung bindet an 0.0.0.0:8000 innerhalb des Containers, damit Docker und NPM sie erreichen können. Compose veröffentlicht auf dem Host nur 127.0.0.1:8000:8000. Der Compose-Dienst verwendet ein dediziertes externes Docker-Netzwerk namens google-mcp-ingress; verbinden Sie nur NPM und diesen Dienst mit diesem Netzwerk. Verwenden Sie nicht das allgemeine proxy-Netzwerk.

Der MCP-Prozess validiert Eingaben und die zulässigen E-Mail-Domänen, erstellt begrenzte Google-Abfragen aus einfachen Suchbegriffen, begrenzt die Suchausgabe, fordert Teilantwortfelder an, filtert domänenübergreifende Aliase, entfernt Steuer-/Formatierungszeichen aus Verzeichnistext und gibt enge, stabile Schemata zurück. Verzeichnistext sind nicht vertrauenswürdige Daten und werden in den MCP-Server-/Tool-Anweisungen ausdrücklich als solche gekennzeichnet; Clients dürfen Namen, Aliase, Pfade oder Abfragen nicht als Anweisungen behandeln. Dies ist eine Kontrolle an der Vertrauensgrenze und kein Ersatz für die System-Prompt-Injections-Abwehr des MCP-Clients.

DWD ist mächtig: Google autorisiert den OAuth-Client und die Bereiche, erzwingt aber nicht die Wahl des festen Betreffs dieser Anwendung. Ein Inhaber des privaten Dienstkontoschlüssels kann anderen Code schreiben, der einen anderen, von DWD zugelassenen Betreff wählt. Dieser Dienst legt GOOGLE_DELEGATED_ADMIN in der Konfiguration fest und akzeptiert den Betreff niemals als Tool-Argument, aber das ist eine Anwendungskontrolle und keine von Google erzwungene Betreffbeschränkung.

Related MCP server: gwsadm-mcp

Phase-1-Werkzeuge

• google_user_status(email)

• google_user_search(query, limit=10); query ist ein einfaches Namens-/E-Mail-Fragment, hartes Maximum 20

• google_user_aliases(email)

• google_user_summary(email)

Jedes explizite E-Mail-Argument muss zu einer der GOOGLE_ALLOWED_DOMAINS gehören, wobei die Groß-/Kleinschreibung nicht berücksichtigt wird. Zurückgegebene Aliaslisten enthalten nur diese Domänen. Sekundäre Workspace-Domänen müssen explizit aufgeführt werden. Der Dienst folgt einem Alias niemals in eine andere Domäne.

Geplant, aber nicht implementiert:

• google_user_groups(email) erfordert den zusätzlichen Bereich https://www.googleapis.com/auth/admin.directory.group.readonly.

In Phase eins ist kein Gruppenbereich und keine Gruppen-API-Operation vorhanden.

Google-Voraussetzungen

Dies sind manuelle Google-Administrationsschritte. Dieses Repository erstellt keine Cloud-Ressourcen oder Anmeldedaten.

1. Erstellen Sie ein dediziertes Google-Cloud-Projekt für diese Arbeitslast.

2. Aktivieren Sie die Admin SDK API (admin.googleapis.com). Für Phase eins ist keine andere Google-API erforderlich.

3. Erstellen Sie ein dediziertes Dienstkonto und aktivieren Sie die Domain-weite Delegierung dafür.

4. Erstellen oder wählen Sie einen dedizierten Workspace-Delegierten-Admin-Benutzer. Eine eng gefasste, benutzerdefinierte Admin-Rolle sollte Folgendes gewähren:

   • Admin API > Benutzer > Lesen (USERS_RETRIEVE)

   • Admin API > Organisationseinheiten > Lesen (ORGANIZATION_UNITS_RETRIEVE)

5. Weisen Sie diese Rolle jeder Organisationseinheit zu, die der Dienst abfragen soll. Verwenden Sie kein tägliches Super-Admin-Konto.

6. Öffnen Sie in der Admin-Konsole Sicherheit > Zugriff und Datenkontrolle > API-Steuerung > Domain-weite Delegierung verwalten. Fügen Sie die numerische OAuth-Client-ID des Dienstkontos hinzu, nicht dessen E-Mail-Adresse.

7. Autorisieren Sie genau diesen Phase-1-Bereich:

   https://www.googleapis.com/auth/admin.directory.user.readonly

8. Erstellen Sie nur dann einen JSON-Schlüssel, wenn derzeit keine schlüssellose Bereitstellungsmethode verfügbar ist. Verschieben Sie ihn sofort in ein Root-/Bereitstellungseigentümer-kontrolliertes Verzeichnis außerhalb dieses Repositorys, legen Sie Host-Berechtigungen wie chmod 600 fest, schränken Sie die Verzeichnisdurchsuchung ein und dokumentieren Sie einen Eigentümer und einen Rotationsplan. Widerrufen Sie den alten Schlüssel nach einer getesteten Rotation.

Der Compose-Mechanismus secrets hängt die Hostdatei schreibgeschützt ein, bietet aber keine Verschlüsselung im Ruhezustand für diese Quelldatei. Hostspeicherschutz, Zugriffskontrolle, Sicherungsbehandlung, Reaktion auf Vorfälle und Rotation bleiben erforderlich. Committen, mailen, in Protokolle einfügen oder in ein Image einbetten Sie den Schlüssel niemals.

Konfiguration

Der normale Start validiert die Konfiguration und den Pfad zur Anmeldedatendatei und erstellt dann delegierte Anmeldedaten. Er schlägt schnell mit einer bereinigten Fehlermeldung fehl, wenn die Initialisierung der Konfiguration oder der Anmeldedaten fehlschlägt. Importe und Unit-Tests erfordern keine Anmeldedaten.

Erstellen und Ausführen

cd google-mcp
cp .env.example .env
chmod 600 .env
# Edit .env; the host credential path must remain outside this repository.
docker compose config
docker compose build
docker compose up -d

Der lokale Endpunkt ist http://127.0.0.1:8000/mcp; NPM sollte http://google-mcp:8000/mcp über das dedizierte Eingangsnetzwerk verwenden. Untersuchen Sie den Start, ohne Geheimnisse offenzulegen:

docker compose ps
docker compose logs --tail=100 google-mcp

NPM befindet sich außerhalb dieses Repositorys und wurde nicht geändert. Fügen Sie das folgende Netzwerk zu dessen Compose-Projekt hinzu, hängen Sie app daran an und erstellen Sie das Netzwerk, bevor Sie beide Projekte starten:

services:
  app:
    networks:
      - proxy
      - google-mcp-ingress

networks:
  google-mcp-ingress:
    external: true
    name: google-mcp-ingress

Erstellen Sie dann einen authentifizierten NPM-Proxy-Host, der an den Hostnamen google-mcp, Port 8000 und Pfad /mcp weiterleitet. Streamable HTTP erfordert die Weiterleitung von POST und GET, wobei der /mcp-Pfad ohne Umschreiben erhalten bleiben muss, die Antwortpufferung deaktiviert sein muss und ausreichend lange Lese-/Sende-Timeouts verwendet werden müssen. Beispiel für eine erweiterte NPM-Konfiguration, nur mit Platzhaltern:

proxy_http_version 1.1;
proxy_buffering off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_set_header Connection "";
proxy_set_header X-MCP-Gateway-Secret "REPLACE_WITH_SECRET_FROM_NPM_SECRET_STORE";
proxy_set_header X-Authenticated-User $remote_user;

NPM muss diese Header überschreiben, nicht Client-Werte durchreichen. Wenn der ausgewählte NPM-Authentifizierungsmechanismus $remote_user nicht befüllt, verwenden Sie einen SSO-/Authentifizierungsproxy, der einen verifizierten Identitätsheader liefert; behandeln Sie das gemeinsame Gateway-Geheimnis nicht als individuelle Aufruferidentität. Aktivieren Sie kein permissives CORS.

Wenn das dedizierte Netzwerk noch nicht existiert, erstellen Sie es, bevor Sie eines der beiden Compose-Projekte starten:

docker network create google-mcp-ingress

Stoppen und entfernen Sie den Container/das Netzwerk, wobei die externe Anmeldedatendatei erhalten bleibt:

docker compose down

Ein MCP-Clientbeispiel finden Sie in examples/mcp-client.json. Dessen URL, Hostname und Token sind Platzhalter. Passen Sie die Form an den jeweiligen Client und das Authentifizierungsgateway an.

Tests

Unit-Tests mocken die Directory-API und nehmen niemals Kontakt zu Google auf:

cd google-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txt
pytest -q

Der Container-Testpfad vermeidet Annahmen über das Host-Python:

docker build --target test -t google-mcp:test .
docker run --rm --user "$(id -u):$(id -g)" --read-only --tmpfs /tmp:size=16m \
  -v "$PWD/tests:/app/tests:ro" \
  google-mcp:test pytest -q -p no:cacheprovider

Das Live-Smoke-Skript wird nur ausgeführt, wenn es explizit aufgerufen wird. Verwenden Sie die folgenden fiktiven Variablen als Platzhalter und setzen Sie echte Testadressen nur in der Shell, niemals in Dateien:

export GOOGLE_TEST_USER='known-active-user@example.test'
export GOOGLE_TEST_MISSING_USER='known-missing-user@example.test' # optional
export GOOGLE_TEST_GATEWAY_SECRET='set-only in the shell; never in a file' # required outside test mode
export GOOGLE_TEST_CALLER='agent1@example.org' # required outside test mode
python tests/smoke_mcp.py http://127.0.0.1:8000/mcp

Es bestätigt die genaue Phase-1-Werkzeugliste, verlangt, dass der bekannte Benutzer ACTIVE zurückgibt, verlangt optional, dass der fehlende Benutzer NOT_FOUND zurückgibt, und gibt nur Zustände aus – keine vollständigen Benutzerdatensätze.

Stabile Antwortschemata

google_user_status gibt genau diese Zustandsfelder zurück. Ein echtes Directory-API-404 ist die einzige NOT_FOUND-Bedingung. ARCHIVED hat Vorrang vor SUSPENDED; alle anderen vorhandenen Benutzer sind ACTIVE. Der Google-Epochen-/Sentinel-Wert für die letzte Anmeldung wird zu null plus never_logged_in: true. Optionale Felder bleiben als null vorhanden, wenn sie deaktiviert sind. Admin-Flags sind standardmäßig null, sofern nicht explizit offengelegt; 2SV-, letzte Anmeldung- und OE-Felder sind standardmäßig offengelegt.

{
  "email": "alex.rivera@example.test",
  "state": "ACTIVE",
  "suspended": false,
  "archived": false,
  "last_login_time": "2026-08-01T13:45:00.000Z",
  "never_logged_in": false,
  "org_unit_path": "/Staff/Campus-A",
  "is_admin": null,
  "is_delegated_admin": null,
  "is_enrolled_in_2sv": true,
  "is_enforced_in_2sv": true
}

Für NOT_FOUND sind boolesche Felder false, Nullable-Felder sind null und never_logged_in ist false, da kein Konto existiert, aus dem auf den Anmeldeverlauf geschlossen werden könnte.

google_user_aliases:

{
  "email": "alex.rivera@example.test",
  "state": "ACTIVE",
  "primary_email": "alex.rivera@example.test",
  "aliases": ["a.rivera@example.test"],
  "non_editable_aliases": ["alex@example.test"]
}

google_user_summary enthält alle Statusfelder plus requested_email, display_name, given_name, family_name, aliases und non_editable_aliases. Es verwendet einen users.get-Aufruf.

google_user_search akzeptiert ein einfaches, von Menschen eingegebenes Fragment, keine Google-Directory-Abfragesyntax. Es erstellt sicher eine E-Mail-Präfix-/Namenspräfix-Abfrage oder eine exakte E-Mail-Abfrage für zulässige Domänen.

google_user_search:

{
  "query": "Alex Rivera",
  "limit": 10,
  "count": 1,
  "truncated": false,
  "next_page_available": false,
  "users": [
    {
      "email": "alex.rivera@example.test",
      "display_name": "Alex Rivera",
      "state": "ACTIVE",
      "suspended": false,
      "archived": false,
      "last_login_time": "2026-08-01T13:45:00.000Z",
      "never_logged_in": false,
      "org_unit_path": "/Staff/Campus-A"
    }
  ]
}

Die konfigurierte Kunden-ID wird immer verwendet. Ergebnisse außerhalb der zulässigen Domänen werden weggelassen und setzen truncated auf true. Das vorgelagerte Seitentoken wird niemals offengelegt; Aufrufer sollten den Begriff eingrenzen, wenn truncated oder next_page_available wahr ist. Begriffe müssen 3..128 Zeichen lang sein und dürfen keine Steuer-/Formatierungszeichen oder rohe Abfragesyntax enthalten. Grenzen außerhalb von 1..20 werden abgelehnt, und es wird nur eine vorgelagerte Seite angefordert.

Protokollierung und Fehlerverhalten

Jeder Tool-Aufruf erzeugt ein strukturiertes JSON-Audit-Ereignis mit UTC-Zeitstempel, generierter Anforderungs-ID, verifizierter Aufruferidentität (oder HMAC-Pseudonym), Tool, maskiertem oder HMAC-pseudonymisiertem Ziel, Ergebnisstatus/-anzahl, Latenz und bereinigter Fehlerkategorie. Der Dienst protokolliert keine Gateway-Geheimnisse, Zugriffstokens, Anmeldedateninhalte oder -pfade, privaten Schlüssel, vollständigen Google-Datensätze, rohe Prompts, Aliase, Namen, Telefon-/Profildaten oder rohe Google-Fehlerantworten.

Nur HTTP 404 wird auf NOT_FOUND abgebildet. HTTP 401/403 werden zu AUTHORIZATION; 429 und zulässige 5xx-Antworten (500, 502, 503, 504) sind insgesamt auf höchstens vier Versuche mit exponentiellem Backoff und Jitter beschränkt. Zeitüberschreitungen und vorübergehende Transportfehler sind ebenfalls begrenzt. Andere fehlerhafte oder Upstream-Fehler bleiben als explizite, bereinigte Fehler erhalten.

Fehlerbehebung

• invalid_grant: Überprüfen Sie, dass das delegierte Subjekt existiert, nicht gesperrt wurde, sich im selben Workspace-Mand eurer zwei syncrhron, die Organsync.sync, und dass die Serveruhr mit synchron ist. Überprüfen Sie außerdem, dass die Anmeldedaten zum DWD-fähigen Dienstkonto gehören.

• unauthorized_client: Verwenden Sie in DWD die numerische OAuth-Client-ID des Service-Kontos und autorisieren Sie den exakt oben gezeigten Scope t. Änderungen in DWD können etwas Zeit in Anspruch.

• 403 / AUTHORIZATION: Überprüfen Sie die Berechtigungen zum Lesen von Benutzern und Organisationseinheiten, den zugewiesenen OU-Scope, die API-Zugriffskontrollen, das delegierte Subjekt und die Admin SDK API. Ein gültiger Schlüssel allein ist nicht.

• Fehlender Scope: Vergleichen Sie den DWD-Eintrag Zeichen für Zeichen mit https://www.googleapis.com/authadmin.directory.user.readonly. In dieser ersten Phase werden bewusst keine Scopes für Gruppen, Drive, Gmail, Kalender, Rollenverwaltung oder Sicherheitsverwaltung angefordert.

• Falsches delegiertes Subjekt: Korrigieren Sie GOOGLE_DELEGATED_ADMIN; es muss der dafür festgelegte delegierte Administrator sein, dessen Rolle die betreffenden OUs abdeckt. Die MCP-Aufrufer können dies nicht entfernen.

• Uhrenverzug: Synchronisieren Sie die Elementuhr des Docker-Hosts. Signierte JWT-Assertions sind zeitkritisch.

• Unerwartetes NOT_FOUND: Vergewissern Sie sich, dass die angeforderte E-Mail-Adresse die konfigurierte zulässige Domain verwendet und ein gegenwärtiger, nicht über den Directory-Benutzer ist. Autorisierungs- und Rate-Limit-Fehler werden niemals zu NOT_FOUND.

Notfall-Widerruf

Bis ein Kompromiss vermuten von die Admin-/Dienst-Verdacht besteht, gilt alle Schritte sicheren:

1. Verwenden Sie die NPM-Route.

2. Stoppen Sie den MCP-Container.

3. Entfernen Sie den DWD-Client-Eintrag, wenn ein Kompromiss vermutet wird die pro ŭmiert wird.

4. Deaktivieren Sie den Dienkappa-Schlüssel.

5. Deaktivieren Sie deant deans delegierte Administrator bei Bedarf.

6. Erhalten Sie die Gateway-, Anwendungs- und Google-Audit-Logs und prüfen Siehen Sie sie.

Hinweis zur WIF-Migration

Die Anmeldedaten-Schnittstelle ist isoliert, sodass später ein anderer Provider hinzugefügt werden kann. In dieser Phase implementiert und testet dieses Release jedoch nur einen gemounteten Dienstkonto-Key. Workload Identity wird keine besondere Asis Anspruch kontakt. Für DWD ist WIF nicht unbedingt ein einfacher Ersatz für einen JSON key: Das Erzeugen der DWD-JWT-Assertion kann IAM-Credentials-signJwt Berechtigungen und explizite Logik erfordern – Sie.