outlook-mcp-server
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/consumersaus (nur persönliche Konten – siehe Tenant-Auswahl), wobei ein kurzlebiger lokaler HTTP-Server als Redirect-Ziel dient. Tokens (einschließlich desoffline_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(Modus0600) geschrieben. Der Schlüssel selbst liegt in~/.outlook-mcp-server/cache.key(ebenfalls0600). Das Bedrohungsmodell, das dies abdeckt (und nicht abdeckt), finden Sie unter Sicherheitshinweise.Graph-Aufrufe: Ein schlanker Client auf Basis von
fetchrufthttps://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 install2. 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:
Rufen Sie portal.azure.com auf und melden Sie sich mit einem beliebigen Microsoft-Konto an.
Suchen Sie nach App-Registrierungen → + Neue Registrierung.
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).
Klicken Sie auf Registrieren, und kopieren Sie anschließend die Anwendungs-(Client-)ID von der Übersichtsseite.
Wechseln Sie zu API-Berechtigungen → + Berechtigung hinzufügen → Microsoft Graph → Delegierte Berechtigungen, und fügen Sie Folgendes hinzu:
Mail.ReadMail.ReadWriteMail.Sendoffline_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.
(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 setupDas führt Folgendes aus:
Die obige Anleitung ausgeben.
Nach der Client-ID fragen (und optional nach Geheimnis / Tenant / Redirect-URI) und sie in
~/.outlook-mcp-server/config.jsonspeichern.Ihren Browser öffnen, um sich anzumelden und zuzustimmen.
Überprüfen, ob das Token funktioniert, indem
GET /meaufgerufen wird und Ihr Name/Ihre E-Mail ausgegeben wird.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 login4. Erstellen und bei Claude registrieren
npm run buildClaude 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.jsStarten Sie Claude Desktop / Claude Code neu. Die unten aufgeführten Tools sollten nun verfügbar sein.
Tools
Tool | Beschreibung |
| Listet Nachrichten aus einem Ordner auf (Standard: |
| Ruft den vollständigen Inhalt (Textkörper, alle Empfänger) einer einzelnen Nachricht anhand der ID ab. |
| Volltextsuche ( |
| Sendet sofort eine E-Mail ( |
| Erstellt einen Entwurf im Ordner „Entwürfe“, ohne ihn zu senden. |
| Listet E-Mail-Ordner und ihre IDs auf, zur Verwendung mit dem Parameter |
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 |
| Client-ID der Azure-App-Registrierung. |
| Nur bei Verwendung eines vertraulichen Clients (Web-Plattform). |
|
|
| Muss mit der Azure-App-Registrierung übereinstimmen. |
| Speicherort für Konfiguration/Tokencache. Standard: |
Sicherheitshinweise
Der Tokencache wird im Ruhezustand mit einem lokal generierten AES-256-GCM-Schlüssel verschlüsselt (
~/.outlook-mcp-server/cache.key, Modus0600). 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 SieICachePlugininsrc/auth/tokenCache.tsgegen eine Variante aus, die auf dem Schlüsselbund Ihres Betriebssystems basiert (z. B. überkeytar) – 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, dieOUTLOOK_MCP_CLIENT_SECRETenthält.send_messagesendet sofort, ohne Bestätigungsschritt innerhalb dieses Servers – Claude soll vor dem Aufruf für sensible Dinge die Absicht mit Ihnen bestätigen. Bevorzugen Siecreate_draft, wenn Sie einen Prüfschritt wünschen.Die angeforderten Berechtigungen beschränken sich auf
Mail.Read,Mail.ReadWrite,Mail.Sendundoffline_access– kein Kalender, keine Kontakte und kein umfassendererMail.*-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 beiconsumersan. Stellen Sie sicher, dass bei der App-Registrierung „Unterstützte Kontotypen“ auf „Nur persönliche Microsoft-Konten“ gesetzt ist und dassOUTLOOK_MCP_TENANTden Wertconsumershat (odercommon, wenn Sie absichtlich beides möchten).AADSTS50011/ Redirect-URI stimmt nicht überein – dieredirectUriin~/.outlook-mcp-server/config.jsonmuss 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 loginaus.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 setupmit 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) setupAvailable Tools
6 toolscreate_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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Related MCP Servers
- AlicenseBqualityCmaintenanceA MCP server for Claude that reads Outlook emails its attachments through the Microsoft Graph API.619MIT
- FlicenseNot gradedqualityDmaintenanceA 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-
- AlicenseNot gradedqualityDmaintenanceMCP server that enables Claude to manage Outlook emails, including reading, sending, organizing, drafting, and bulk operations via Microsoft Graph API.15 npm1MIT
- AlicenseAqualityDmaintenanceAn 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.312MIT