outlook-mcp-server

Ein lokaler MCP-Server, der Claude (Desktop oder Code) Lese- und Schreibzugriff auf ein persönliches Hotmail-/Outlook.com-Postfach über die Microsoft Graph API gewährt, unter Verwendung des OAuth-2.0-Autorisierungscode-Flows (mit PKCE) gegen die Microsoft-Identitätsplattform.

Er stellt sechs Tools bereit: list_messages, get_message, search_messages, send_message, create_draft und list_folders.

Alles läuft lokal über stdio — es gibt keinen gehosteten Dienst, und Ihre E-Mails laufen über nichts anderes als Ihren Rechner und Microsofts eigene Graph API.

So funktioniert es

• Authentifizierung: MSAL Node führt einen Autorisierungscode- und PKCE-Flow gegen https://login.microsoftonline.com/consumers aus (nur persönliche Konten – siehe Tenant-Auswahl), wobei ein kurzlebiger lokaler HTTP-Server als Redirect-Ziel dient. Tokens (einschließlich des offline_access-Aktualisierungstokens) werden zwischengespeichert und bei späteren Ausführungen stillschweigend aktualisiert.

• Speicherung: Der Tokencache wird von MSAL serialisiert, mit einem lokal generierten Schlüssel per AES-256-GCM verschlüsselt und nach ~/.outlook-mcp-server/token-cache.enc (Modus 0600) geschrieben. Der Schlüssel selbst liegt in ~/.outlook-mcp-server/cache.key (ebenfalls 0600). Das Bedrohungsmodell, das dies abdeckt (und nicht abdeckt), finden Sie unter Sicherheitshinweise.

• Graph-Aufrufe: Ein schlanker Client auf Basis von fetch ruft https://graph.microsoft.com/v1.0/... mit dem aktuellen Zugriffstoken auf.

• MCP-Server: Basierend auf @modelcontextprotocol/sdk, kommuniziert über stdio, sodass er von Claude Desktop / Claude Code direkt als Kindprozess gestartet werden kann.

Related MCP server: Outlook MCP Python

Voraussetzungen

• Node.js 18+

• Ein Microsoft-Konto (Hotmail, Outlook.com oder Live) – das Postfach, auf das Claude zugreifen soll.

• Ein kostenloses Azure-Konto, um die App zu registrieren (jedes Microsoft-Konto ist dazu in der Lage – es muss kein kostenpflichtiges Azure-Abonnement sein).

1. Installation

git clone <this repo>
cd outlook-mcp-server
npm install

2. Registrieren Sie eine App im Azure-Portal

Diese Registrierung stellt die Client-ID aus, die dieser Server verwendet, um in Ihrem Namen mit Microsoft Graph zu kommunizieren. npm run setup (weiter unten) führt Sie interaktiv durch den Vorgang, aber die Schritte sind:

1. Rufen Sie portal.azure.com auf und melden Sie sich mit einem beliebigen Microsoft-Konto an.

2. Suchen Sie nach App-Registrierungen → + Neue Registrierung.

3. Füllen Sie das Formular aus:

   • Name: irgendetwas, z. B. outlook-mcp-server.

   • Unterstützte Kontotypen: „Nur persönliche Microsoft-Konten“. Dadurch wird die App auf Hotmail-/Outlook.com-/Live-Konten beschränkt statt auf einen Geschäfts-/Schulmandanten (Azure AD).

   • Redirect-URI: Plattform „Öffentlicher Client/nativ (Mobilgerät & Desktop)“, Wert http://localhost:8765/callback (oder ein anderer Port – achten Sie nur darauf, konsistent zu sein, wenn das Setup-Skript danach fragt).

4. Klicken Sie auf Registrieren, und kopieren Sie anschließend die Anwendungs-(Client-)ID von der Übersichtsseite.

5. Wechseln Sie zu API-Berechtigungen → + Berechtigung hinzufügen → Microsoft Graph → Delegierte Berechtigungen, und fügen Sie Folgendes hinzu:

   • Mail.Read

   • Mail.ReadWrite

   • Mail.Send

   • offline_access (oft standardmäßig vorhanden)

   Delegierte Berechtigungen für persönliche Microsoft-Konten wie diese benötigen keine Administratorzustimmung – Sie stimmen selbst bei der Anmeldung in Schritt 3 weiter unten zu.

6. (Optional, fortgeschritten) Wenn Sie lieber einen vertraulichen Client mit einem Clientschlüssel anstelle des Public-Client-PKCE-Flows verwenden möchten, fügen Sie eine Redirect-URI der Plattform Web hinzu und erstellen Sie unter Zertifikate & Geheimnisse einen Schlüssel. Die meisten Personen sollten diesen Schritt überspringen.

3. Setup ausführen (Authentifizierung + Konfiguration)

npm run setup

Das führt Folgendes aus:

1. Die obige Anleitung ausgeben.

2. Nach der Client-ID fragen (und optional nach Geheimnis / Tenant / Redirect-URI) und sie in ~/.outlook-mcp-server/config.json speichern.

3. Ihren Browser öffnen, um sich anzumelden und zuzustimmen.

4. Überprüfen, ob das Token funktioniert, indem GET /me aufgerufen wird und Ihr Name/Ihre E-Mail ausgegeben wird.

5. Den JSON-Ausschnitt ausgeben, den Sie zu Ihrer Claude-Konfiguration hinzufügen können (siehe unten).

Um sich später erneut zu authentifizieren (widerrufenes Token, Kontowechsel usw.), ohne die App-Registrierungsdaten erneut einzugeben:

npm run login

4. Erstellen und bei Claude registrieren

npm run build

Claude Desktop – fügen Sie zu claude_desktop_config.json hinzu (~/Library/Application Support/Claude/claude_desktop_config.json unter macOS, %APPDATA%\Claude\claude_desktop_config.json unter Windows):

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/absolute/path/to/outlook-mcp-server/dist/src/index.js"]
    }
  }
}

Claude Code:

claude mcp add outlook -- node /absolute/path/to/outlook-mcp-server/dist/src/index.js

Starten Sie Claude Desktop / Claude Code neu. Die unten aufgeführten Tools sollten nun verfügbar sein.

Tools

Alle Tools geben JSON zurück (als MCP-Textinhalt) und melden Graph-API-Fehler als Tool-Fehler, anstatt den Server zum Absturz zu bringen.

Tenant-Auswahl

Standardmäßig wird der consumers-Tenant verwendet (https://login.microsoftonline.com/consumers), der nur persönliche Microsoft-Konten (Hotmail/Outlook.com/Live) akzeptiert – ein Geschäfts- oder Schulkonto wird bei der Anmeldung abgelehnt. Wenn Sie sowohl persönliche als auch Azure-AD-Konten unterstützen müssen, setzen Sie den Tenant während npm run setup auf common (oder über OUTLOOK_MCP_TENANT=common). Dieses Projekt ist für den Fall persönlicher Konten (consumers) konzipiert und getestet.

Konfigurationsreferenz

Alles kann über npm run setup (geschrieben nach ~/.outlook-mcp-server/config.json) oder über Umgebungsvariablen festgelegt werden, die Vorrang haben – siehe .env.example:

Sicherheitshinweise

• Der Tokencache wird im Ruhezustand mit einem lokal generierten AES-256-GCM-Schlüssel verschlüsselt (~/.outlook-mcp-server/cache.key, Modus 0600). Dies schützt vor versehentlicher Offenlegung – unbeabsichtigte Commits, Backups, andere unprivilegierte Benutzer auf einem gemeinsam genutzten Rechner –, aber nicht vor einem Angreifer, der bereits Lesezugriff auf die Dateien Ihres Benutzerkontos hat, da der Schlüssel neben dem verschlüsselten Cache liegt. Für stärkeren Schutz tauschen Sie ICachePlugin in src/auth/tokenCache.ts gegen eine Variante aus, die auf dem Schlüsselbund Ihres Betriebssystems basiert (z. B. über keytar) – das Plugin-Interface ist bewusst auf diese eine Datei isoliert.

• Committen Sie niemals ~/.outlook-mcp-server/ (dieser Ordner liegt standardmäßig außerhalb des Repos) oder eine .env-Datei, die OUTLOOK_MCP_CLIENT_SECRET enthält.

• send_message sendet sofort, ohne Bestätigungsschritt innerhalb dieses Servers – Claude soll vor dem Aufruf für sensible Dinge die Absicht mit Ihnen bestätigen. Bevorzugen Sie create_draft, wenn Sie einen Prüfschritt wünschen.

• Die angeforderten Berechtigungen beschränken sich auf Mail.Read, Mail.ReadWrite, Mail.Send und offline_access – kein Kalender, keine Kontakte und kein umfassenderer Mail.*-Zugriff auf Anwendungsebene.

Fehlerbehebung

• AADSTS50020 / „user account ... does not exist in tenant“ – Sie stoßen auf einen Tenant, der keine persönlichen Konten akzeptiert, oder Sie melden sich mit einem Geschäfts-/Schulkonto bei consumers an. Stellen Sie sicher, dass bei der App-Registrierung „Unterstützte Kontotypen“ auf „Nur persönliche Microsoft-Konten“ gesetzt ist und dass OUTLOOK_MCP_TENANT den Wert consumers hat (oder common, wenn Sie absichtlich beides möchten).

• AADSTS50011 / Redirect-URI stimmt nicht überein – die redirectUri in ~/.outlook-mcp-server/config.json muss exakt mit einer in der Azure-App-Registrierung konfigurierten Redirect-URI übereinstimmen, einschließlich des Ports.

• „Not signed in“-Toolfehler – führen Sie npm run login aus.

• Port während Setup/Anmeldung bereits belegt – ein anderer Prozess verwendet den Port der Redirect-URI; beenden Sie diesen, oder konfigurieren Sie die App-Registrierung und npm run setup mit einem anderen Port neu.

Entwicklung

npm run dev     # run the MCP server directly from TypeScript (stdio)
npm run build   # compile to dist/
npm run clean   # remove dist/

Projektstruktur

src/
  index.ts            MCP server entrypoint (stdio transport)
  config.ts            Config loading (env + config file)
  auth/
    crypto.ts           AES-256-GCM file encryption helpers
    tokenCache.ts        MSAL ICachePlugin backed by crypto.ts
    msalClient.ts        MSAL app factory + silent token acquisition
    loginFlow.ts          Interactive loopback OAuth flow
  graph/
    client.ts            Generic Microsoft Graph fetch wrapper
    mail.ts               Mail-specific Graph calls
    types.ts              Graph response types
  tools/                 One file per MCP tool, registered in index.ts
scripts/
  setup.ts              Interactive one-time (and re-runnable) setup