Skip to main content
Glama
outlook-mcp-server

outlook-mcp-server

by acangialosi

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

Tool

Beschreibung

list_messages

Listet Nachrichten aus einem Ordner auf (Standard: inbox) mit Datumsfiltern für since/until, unreadOnly, Sortierung und Paginierung.

get_message

Ruft den vollständigen Inhalt (Textkörper, alle Empfänger) einer einzelnen Nachricht anhand der ID ab.

search_messages

Volltextsuche ($search) in E-Mails, optional auf einen Ordner eingeschränkt.

send_message

Sendet sofort eine E-Mail (to/cc/bcc, Betreff, Text- oder HTML-Inhalt).

create_draft

Erstellt einen Entwurf im Ordner „Entwürfe“, ohne ihn zu senden.

list_folders

Listet E-Mail-Ordner und ihre IDs auf, zur Verwendung mit dem Parameter folder weiter oben.

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:

Variable

Zweck

OUTLOOK_MCP_CLIENT_ID

Client-ID der Azure-App-Registrierung.

OUTLOOK_MCP_CLIENT_SECRET

Nur bei Verwendung eines vertraulichen Clients (Web-Plattform).

OUTLOOK_MCP_TENANT

consumers (Standard) oder common.

OUTLOOK_MCP_REDIRECT_URI

Muss mit der Azure-App-Registrierung übereinstimmen.

OUTLOOK_MCP_CONFIG_DIR

Speicherort für Konfiguration/Tokencache. Standard: ~/.outlook-mcp-server.

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

Available Tools

6 tools
create_draftCreate a draft emailA

Create a draft message in the mailbox's Drafts folder without sending it. Prefer this over send_message whenever the user should review the email first.

Inputs: cc, to, bcc, body, +2 more.

get_messageGet full email messageA

Fetch the full content (including body, all recipients, and sender) of a single message by its Graph message ID, as returned by list_messages or search_messages.

Inputs: messageId (required).

list_foldersList mail foldersA

List top-level mail folders in the mailbox (Inbox, Sent Items, Drafts, Archive, custom folders, etc.) along with their IDs and item counts. Use a returned folder ID with list_messages or search_messages to target that folder.

Inputs: no named parameters.

list_messagesList email messagesA

List messages from a mail folder (default: inbox), newest first by default. Supports date-range and read/unread filtering. Use list_folders first if you need a folder ID other than a well-known name like 'inbox', 'drafts', 'sentitems', 'archive', or 'junkemail'.

Inputs: top, skip, since, until, +4 more.

search_messagesSearch email messagesA

Full-text search across mail (subject, body, sender, recipients, attachments) using Microsoft Graph's $search, ranked by relevance. Optionally scope the search to one folder. For structured filtering (date ranges, read/unread) without free-text search, prefer list_messages instead.

Inputs: query (required), top, folder.

send_messageSend an emailA

Send a new email immediately from the signed-in mailbox. This sends right away — there is no confirmation step, so only call this once you (and the user, if appropriate) are sure about the recipients and content. Use create_draft instead if the message should be reviewed before sending.

Inputs: to (required), body (required), subject (required), cc, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: listing, fetching, searching, folder enumeration, sending, and drafting. The only possible confusion is between list_messages and search_messages, but their descriptions clearly differentiate structured filtering from full-text relevance search.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: list_messages, get_message, search_messages, list_folders, send_message, create_draft. There are no style mixups or vague verbs.

    Tool Count5/5

    Six tools is a well-scoped set for an Outlook mail server. Each tool covers a distinct core email operation without unnecessary bloat or missing essentials.

    Completeness4/5

    The tool surface covers the primary mail workflows: listing, searching, reading, sending, drafting, and folder navigation. Some common operations like reply, forward, delete, move, or updating drafts are absent, but the core read/send workflow is solid.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Python-based MCP server for Microsoft Outlook integration using Microsoft Graph API, enabling email reading/sending, calendar management, and contact operations through Claude Desktop.
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that enables Claude to manage Outlook emails, including reading, sending, organizing, drafting, and bulk operations via Microsoft Graph API.
      15 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that gives Claude Code and Codex full control of a personal Outlook.com mailbox and calendar via the Microsoft Graph API, enabling mail, draft, folder, and calendar operations through natural language.
      31
      2
      MIT