Microsoft 365 Reporting MCP — v1.0

Enterprise-MCP-Server, über den ChatGPT, Claude und andere MCP-kompatible KI-Clients kontrolliert auf die Microsoft-365-Informationsquellen zugreifen (Outlook, Kalender, Teams, Meeting-Transkripte, OneNote, SharePoint, OneDrive, Loop, Search, Users).

Grundsatz: read broadly, write narrowly. Eine breite READ-Ebene innerhalb der tatsächlichen M365-Berechtigungen des angemeldeten Benutzers; die einzige WRITE-Fähigkeit ist das Senden von Outlook-E-Mails (draft / send / reply / forward), wobei jedes tatsächliche Senden über ein separates confirm=true-Gate läuft.

Architektur

ChatGPT / Claude / MCP kliens
        │  MCP over HTTPS (Streamable HTTP) + OAuth bearer token
        ▼
┌──────────────────────────────┐
│  m365-reporting-mcp          │   Tool allowlist (86 tool, 11 WRITE = csak mail)
│  · JWT validálás (Entra)     │   Nincs generikus graph-request / $batch passthrough
│  · On-Behalf-Of tokencsere   │   Audit log (JSONL, tartalom nélkül)
│  · Pagination + 429 retry    │   Forráskövetés (_source blokk minden objektumon)
│  · Admin dashboard (/admin)  │
└──────────────┬───────────────┘
               │  OAuth 2.0 OBO → delegated Graph token
               ▼
    Microsoft Entra ID → Microsoft Graph API (v1.0)

Der Server verwendet niemals App-only-Berechtigungen: Jeder Graph-Aufruf läuft im Namen des angemeldeten Benutzers (delegiert), sodass das MCP die bestehenden M365-Zugriffsregeln nicht umgehen kann.

Related MCP server: Microsoft Graph MCP Server

Entra-ID-App-Registrierung

1. App registration erstellen (single tenant).

2. Expose an API: Application ID URI = api://<CLIENT_ID>, scope: access_as_user. Setze wurde die accessTokenAcceptedVersion auf 2 (Manifest).

3. API permissions (Microsoft Graph, Delegated) — Die vollständige Liste befindet sich im Anhang docs/tool-matrix.md; zusammengefasst:

   • READ: Mail.Read, Mail.Read.Shared, Calendars.Read, Chat.Read, Team.ReadBasic.All, Channel.ReadBasic.All, ChannelMessage.Read.All, TeamMember.Read.All, OnlineMeetings.Read, OnlineMeetingTranscript.Read.All, OnlineMeetingRecording.Read.All, OnlineMeetingArtifact.Read.All, Notes.Read, Notes.Read.All, Sites.Read.All, Files.Read, Files.Read.All, People.Read, User.Read, User.ReadBasic.All, User.Read.All

   • WRITE (nur Mail): Mail.ReadWrite, Mail.Send, Mail.ReadWrite.Shared, Mail.Send.Shared

   • Für die .All- Scopes ist Admin Consent erforderlich.

4. für den HTTP-Modus: Certificates & secrets → Client Secret.

5. für den stdio/Dev-Modus: Authentication → „Allow public client flows“ = Yes (device code).

Anmerkung zu Punkt 11 der Spezifikation: Sites.Selected existiert nur als application-Berechtig; im delegierten Modell (im Namen des Benutzers) ergibt die site-spezifische Einschränkung sich aus der eigenen SharePoint-Berechtigung des Benutzers — das MCP verwendet delegiertes Sites.Read.All, das für sich genommen keinen Zugriffs auf eine Site gewährt, die der Benutzer andernfalls nicht erreicht.

Installation und Ausführung

npm install
cp .env.example .env      # töltsd ki: TENANT_ID, CLIENT_ID, CLIENT_SECRET, BASE_URL, ADMIN_KEY
npm run build

# Webapp (remote MCP) mód:
npm run start:http

# Lokális/dev (stdio, device code login):
npm run login             # egyszeri bejelentkezés, token cache-elve
npm start

Endpunkte im HTTP-Modus:

Im HTTP-Modus startet der Server auch ohne Entra-Daten: Die Ersteinrichtung kann über die /admin-Obfläche erfolgen (Tenant ID, Client ID, Client Secret, Base URL, Verbindungstest) — das Speichern wird sofort wirksamber, die Einstellungen werden in data/settings.json gespeichert und überscchreibeen die Werte aus .env.

ChatGPT (und andere MCP-Client)s verbinden

Der Server enthält einen integrierten OAuth-Proxyvor der Entra ID, weil der ChatGPT-Connell eine dynamic client registration nachRFC 7591 erwartet, die das Entra nicht unterstützt. Der Prox bietet dem Klient gegenüber eine volle OAuth-2.1-Schnittstelle (DCR + PCKE) und verwendet gegenüber Entra die eiznige registrierte Unternehmels-App. Das an den Klient ausgegebene Access-Tokenist exactly the same Token, das Entra für api://<CLIENT_ID> ausgestellt hat — damit bleibt die Valid under /mcps and der OBO-Graph-purpose unverändaltet; alle Aufrufe laufen im Namen des angemeldeten Benutzers.

Verbinden vonChatGPT aus:

1. Füge im Bereich Authentication der Entra-App die Web-Redirect-URI https://<BASE_URL>/aut/callback hinzu (den genau Wert zeigt der Tab „Einstellungen“ im Admin-Breech).

2. ChatGPT → Settings →Connectors → neuenMCP-Connector, URL: https://<BASE_URL>/mcp.

3. Die angezeigte Anmeldung ist die Unternehmens-Anmeldung des Entra ID — der Benutzer meldet sich mit seinem eigenen einscom Konto in und erhält only the eigenen M365-Berechtigungen.

Claude Desktop / Claude Code: diesel e URL alsremoteMCP, oder lokal im Stdio-Modus (claude mcp add m365-reporting -- node dist/index.js --stdio).

Sicherheitsschicht (spec 19–20)

• Kein generisches Tool graph_request(method, url, body) und kein $batch-Passthrough — es sind nur die 86 in der Allowlist befindlichen Endpunkte erreichbar.

• Kein Schreiben aufCalendar/Teams/Files/Sites/Wunsch/User/Group und kein Delete an keinem Punkt.

• Draft-Erstellung ≠ Sendeberechtigung: Jedes Senden/Antworten/Weiterleiten verlangt confirm=true; die Tool-Beschreibung weist dieKI an, vorher explizite Zustimmung von Benutzer einzuholen.

• MREAD_ONLY=true(env) alle write modes turn-off; mit ENABLED_TOOLSETS lässt sich und das Profil auf Toolset-Ebene einschränken (z. B. mail,calendar,meetings).

Audit (spec21)

Jede Aufruf protokolliert in JSONL (logs/audit-YYYY-MM-DD.jsonl): timestamp, user, session, tool, operation (READ/WRITE), resourceType, graphEndpoint, httpMethod, success, durationMs, bei WRITE zusätzlich sender, recipients, cc, subject, messageId, result. Inhalt (body, transcript, document, token) gelangt nie in die Logs.

Fehler Toleranz (spec22-23)

• HTTP 429/503/504:automatisches Retry unter berücksichtig vonRetry-After (max. 4 Versuche);

• @odata.nextLink-Pagination bei allen List/Werkzeugen (maxItems-Parameter,bezeichnete Kürzung);

• Abgelaufene Token / restricted access / fehlender resource: verständliche, umsetzbare Fehlermeldung fürAI;

• Datei-Download mit Größenlimit (MAX_DOWNLOAD_BYTES), DOCX/XLSX/PPTX/PDF/TXT/CSV → Textextraktion, anderer Binärinhalt → base64.

Tool-Matrix (Entwickler-Anhang)

Die vollständige Matrix MCP tool → Graph endpoint → HTTP method → delegated permission → READ/WRITE → enabled als generiertes Dokument: docs/tool-Matrix.md (npm run matrix aktualisiert sie aus den Definitionen in src/tools/endpoints/*.ts).

Einschränkungen des Loop-Adapters (spec 13)

Es gibt keine allgemein verfügbare dedizierte Graph-Loop-Workspace-API, daher verwendet der Loop-Adapter keine fiktiven Endpunkte: Die .loop/.fluid-Komponenten werden über die Search-API und über SharePoint/OneDrive-Laufwerke angeiprochen. Loop-Workspaces in SharePoint-Embedded-Container sind über den delegated Graph möglicherweise nicht erreichbar — dieser Tool description meldefd dies derKI, damit sie die Grenze auch dem Benutzer gegenüber anzeigt.

Abnahmetest (spec 26)

Aus einem verbundenen Client in natürlicher Sprache: „Untersuche meine E-Mails, meinen Kalender, Teams-Unterhaltungen und Meeting-Transkripte der letzten 30 Tage… Erstelle eine Zusammenfassung über Projekt X… Erstelle daraus eine E-Mail und sende sie erst nach besonderer Zustellung ab.“ — die erwartete Werkzeugkette: get-calendar-view · find-online-meeting-by-join-url · list-meeting-transcripts → get-meeting-transcript-content + list-mail-messages + list-chat-messages + search-onenote-pages + search-m365 → create-draft-email → (Benutzer-zustimmung) → send-draft-email(confirm=true).