outlook-ews-mcp

outlook-ews-mcp ist ein MCP-Server für lokales Microsoft Exchange über EWS (exchangelib). Er bietet MCP-kompatiblen Clients (Claude Desktop, Claude Code und jedem anderen MCP-Client) Zugriff auf E-Mail, Kalender, Kontakte, Ordner, Anhänge und Verfügbarkeitsdaten über einen einzigen, testbaren Python-Dienst – ohne direkte Mailbox-Skripte.

Umbenannt von outlook-mcp. Dieser Name war auf PyPI bereits von einem unabhängigen Projekt belegt, daher heißen Distribution und CLI jetzt outlook-ews-mcp. Der Python-Importpfad ist unverändert. Bis zur ersten getaggten PyPI-Veröffentlichung installieren Sie aus diesem Repository wie unten gezeigt.

Inhalt

• Highlights

• Werkzeugkatalog

• Typische Anwendungsfälle

• Sicherheitshinweise

• Schnellstart

• Konfiguration

• Anfragewarteschlange

• Claude-Desktop-Beispiel

• Rauchtest

• Docker

• CI/CD

• Entwicklung

• Projektnotizen

• Mitwirken

• Lizenz

Related MCP server: owa-mail-mcp

Highlights

• E-Mail – auflisten, suchen (Teilstring oder Advanced Query Syntax), lesen, senden, antworten, weiterleiten, verschieben, kopieren, löschen, markieren, kategorisieren, Massenaktionen, roher MIME-Export, Anhänge hinzufügen/löschen

• System – Posteingangsregeln, Abwesenheitsnotiz (automatische Antworten), schreibgeschützte Delegiertenliste

• Kalender – auflisten, erstellen, aktualisieren, löschen, auf Einladungen antworten, freie Zeitfenster finden, Kalender eines freigegebenen/delegierten Postfachs anzeigen, Raumfinder, Massenaktionen

• Kontakte – suchen, lesen, erstellen, aktualisieren, löschen

• Ordner & Anhänge – Ordner-CRUD und Anhangs-Download

• Authentifizierung – NTLM und Basic gegen lokales Exchange

• Transport – stdio und SSE

• Architektur – zentrales Fehler-Mapping durch eine einzige ExchangeClient-Abstraktion (siehe Projektnotizen)

• Sicherheit – ein datenschutzfreundlicherer Rauchtest standardmäßig (siehe Rauchtest)

• Betrieb – Docker-Image sowie GitHub- und GitLab-CI/CD-Pipelines enthalten

Werkzeugkatalog

Jedes unten aufgeführte Werkzeug ist in tool_specs.py registriert, der einzigen Quelle der Wahrheit für Name, Beschreibung und Schema. Schreibgeschützt markiert Werkzeuge, die das Postfach nie verändern – sie erhalten mehr Parallelität (siehe Anfragewarteschlange) und können bedenkenlos spekulativ aufgerufen werden.

System

⚠️ create_inbox_rule / update_inbox_rule / delete_inbox_rule verwalten Regeln über EWS, wodurch der clientseitige Regel-Blob entfernt wird, den Desktop-Outlook behält – dies kann Regeln löschen, die ein Benutzer in Outlook selbst erstellt hat. Dies ist dokumentiertes EWS-Verhalten, kein Fehler hier.

E-Mail

Kalender

Kontakte

Typische Anwendungsfälle

• Claude Desktop oder einen anderen MCP-Client mit lokalem Exchange verbinden

• Posteingangsnachrichten durchsuchen und vollständigen E-Mail-Inhalt abrufen

• E-Mails aus KI-Workflows senden oder entwerfen

• Kalender einsehen und Besprechungen erstellen

• Frei/Gebucht-Zeitfenster für die Terminplanung prüfen

• Persönliche Kontakte oder die globale Adressliste durchsuchen

• Exchange-Operationen über eine kontrollierte MCP-Grenze bereitstellen, statt direkt per Skript auf Postfächer zuzugreifen

Sicherheitshinweise

Was der aktuelle Code tut:

Worauf Sie weiterhin achten sollten:

• EXCHANGE_VERIFY_SSL=false deaktiviert die TLS-Zertifikatsprüfung – nur für vertrauenswürdige interne/self-signed Umgebungen.

• EXCHANGE_AUTH_TYPE=Basic sendet Anmeldedaten im Klartext, daher weigert sich der Server, gegen einen http://-EXCHANGE_SERVER zu starten; nur mit EXCHANGE_ALLOW_INSECURE_BASIC_AUTH=true für einen lokalen/Test-Server, den Sie kontrollieren, überschreiben.

• get_attachment schreibt Dateien auf die Festplatte, und send_email/reply_email/forward_email/ create_draft lesen lokale Dateien (über attachments) und hängen deren Inhalte an ausgehende E-Mails an. In Kombination mit nicht vertrauenswürdigem E-Mail-Inhalt ist dies ein plausibler Weg für prompt-injizierte Exfiltration beliebiger Dateien, die der Prozess lesen kann. Lokaler Dateizugriff ist standardmäßig verweigert und funktioniert erst, wenn EXCHANGE_ATTACHMENT_ROOT auf ein absolutes Verzeichnis gesetzt ist, das dann sowohl attachments-Pfade als auch save_path von get_attachment's auf diesen Verzeichnisbaum beschränkt (ein nicht gesetztes save_path fällt weiterhin auf das System-Temp-Verzeichnis zurück).

• outlook-ews-mcp-smoke ist standardmäßig datenschutzsicher und gibt nur maskierte Postfachinformationen plus Zähler aus; setzen Sie OUTLOOK_MCP_SMOKE_INCLUDE_DATA=true nur, wenn Sie explizit echte Posteingangs-/Ereignisdaten in stdout möchten.

• Wenn Sie Dateiprotokollierung mit LOG_FILE aktivieren, schützen Sie diese Datei mit Betriebssystemberechtigungen.

• Wenn Sie Docker-Images aus CI veröffentlichen, schützen Sie den GitLab/GitHub-Projektzugriff und die Registry-Berechtigungen.

Schnellstart

uv venv
source .venv/bin/activate
uv pip install -e .[dev]
cp .env.example .env
outlook-ews-mcp

Standardmäßig läuft der Server im stdio-Modus. Setzen Sie MCP_TRANSPORT=sse, um stattdessen einen HTTP-Server zu starten.

Konfiguration

Minimale .env für den Einstieg – alles andere unten hat einen funktionierenden Standardwert:

EXCHANGE_SERVER=https://mail.company.com/EWS/Exchange.asmx
EXCHANGE_USERNAME=DOMAIN\username
EXCHANGE_PASSWORD=secret
EXCHANGE_EMAIL_ADDRESS=user@company.com
EXCHANGE_AUTH_TYPE=NTLM

Eine vollständig kommentierte Kopie jeder Variable befindet sich in .env.example.

Verhaltenshinweise, die nicht an eine einzelne Variable gebunden sind:

• list_events und find_free_slots akzeptieren ein begrenztes limit (Standard 200, Maximum 1000); Ereigniszeiträume sind auf 366 Tage und Zeitfenster für freie Slots auf 31 Tage begrenzt, sodass breite Abfragen keine unbegrenzten EWS- oder MCP-Antworten erzeugen können.

• Auflistungen bleiben bewusst schlank: E-Mail-Zusammenfassungen enthalten den Absender, aber keine Empfängerlisten (get_email hat sie), list_events gibt Ereignisse ohne Textkörper zurück (get_event hat sie), und get_email gibt RFC-822-Header nur mit include_headers: true zurück.

• Sendevorgänge geben id: null zurück, wenn EWS keine dauerhafte ID für die gesendete Kopie bereitstellt (insbesondere Antworten, Weiterleitungen und gesendete Entwürfe).

• Anhangsmetadaten enthalten downloadable; eingebettete Exchange-Elementanhänge haben downloadable: false und können nicht mit get_attachment gespeichert werden.

Anfragewarteschlange

Clients geben mehrere Tool-Aufrufe parallel aus. Exchange-Arbeit ist blockierend, daher führt der Server sie in Worker-Threads aus und lässt Aufrufe über eine gemeinsame FIFO-Warteschlange zu.

• MCP_MAX_CONCURRENCY (Standard 4) legt fest, wie viele schreibgeschützte Aufrufe gleichzeitig laufen, sodass ein Agent, der eine E-Mail, die Ordnerliste und den Kalender anfordert, die langsamste Roundtrip-Zeit zahlt statt der Summe. Mutierende Aufrufe laufen immer exklusiv — einer nach dem anderen, nie überlappend mit einem Lesevorgang — sodass Lese-/Schreib-Wettläufe auf gemeinsamen Kontozustand nicht auftreten können. Aufrufer über dem Limit warten, in der Reihenfolge ihres Eintreffens; ein wartender Schreibvorgang verhindert, dass spätere Lesevorgänge ihn überholen.

• MCP_MAX_QUEUE_SIZE (Standard 20) begrenzt, wie viele Aufrufe gleichzeitig zugelassen werden können, laufend oder wartend. Sobald so viele bereits in der Warteschlange sind, erhalten weitere Aufrufe sofort einen server_busy-Fehler, statt sich einer unbegrenzten Warteschlange anzuschließen.

• Der Transport bleibt reaktionsfähig, während Arbeit läuft. Tools werden awaited statt auf dem Event-Loop-Thread ausgeführt, sodass fertige Antworten sofort hinausgehen und Pings beantwortet werden, während ein langer Aufruf noch läuft.

• Es gibt bewusst kein Timeout pro Aufruf. Ein Thread, der auf einem Socket-Read blockiert, kann von außen nicht beendet werden; die Laufzeit kann nur aufhören, auf ihn zu warten, was den Thread zusammen mit der EWS-Sitzung, die er hält, aufgibt. Der Sitzungspool von exchangelib hat ein hartes Maximum und gibt Sitzungen in einer Schleife ohne Aufgabepfad aus, sodass verlorene Sitzungen ihn schließlich aushungern und jeder spätere Aufruf für immer blockiert. Ein langsamer Aufruf wird stattdessen ausgesessen, begrenzt durch EXCHANGE_TIMEOUT plus EXCHANGE_MAX_RETRY_WAIT_SECONDS: Die Retry-Richtlinie des Kontos ist Fail-Fast, sodass jeder EWS-Aufruf bei seinem ersten transienten Fehler eine Ausnahme auslöst, statt dass exchangelib intern endlos wiederholt, und ExchangeClient wiederholt selbst nur schreibgeschützte Aufrufe, begrenzt durch dieses Wanduhr-Budget. Schreibvorgänge werden nie automatisch wiederholt. Überschreitungen über das erwartete Budget hinaus werden protokolliert.

Claude Desktop-Beispiel

{
  "mcpServers": {
    "outlook": {
      "command": "outlook-ews-mcp",
      "env": {
        "EXCHANGE_SERVER": "https://mail.company.com/EWS/Exchange.asmx",
        "EXCHANGE_USERNAME": "DOMAIN\\username",
        "EXCHANGE_PASSWORD": "secret",
        "EXCHANGE_EMAIL_ADDRESS": "user@company.com",
        "EXCHANGE_AUTH_TYPE": "NTLM"
      }
    }
  }
}

Smoke-Check

Nach dem Ausfüllen von .env ausführen:

outlook-ews-mcp-smoke

Die Standardausgabe wird zur sichereren Überprüfung bereinigt. Wenn Sie absichtlich Beispieldaten für Postfach/Ereignisse in der Ausgabe wünschen:

OUTLOOK_MCP_SMOKE_INCLUDE_DATA=true outlook-ews-mcp-smoke

Docker

docker build -t outlook-ews-mcp .
docker run --rm --env-file .env outlook-ews-mcp

CI/CD

GitHub Actions und GitLab CI führen beide Lint, Formatierung, Typprüfungen, Tests, Abhängigkeitsaudit und Paket-Builds aus, unter Verwendung der in pyproject.toml festgelegten uv-Version.

Standardmäßiges Image-Tagging-Verhalten:

Entwicklung

uv run --python 3.12 --with '.[dev]' ruff check .
uv run --python 3.12 --with '.[dev]' pytest -q

Projektnotizen

• Die Implementierung ist um eine einzige ExchangeClient-Abstraktion zentriert, sodass Authentifizierung, Transport, Retries und Fehlerzuordnung zentralisiert bleiben.

• Fehler werden in einer strukturierten JSON-Form zurückgegeben, die für die MCP-isError=true-Behandlung geeignet ist.

Mitwirken

Fehlerberichte und PRs sind willkommen — siehe CONTRIBUTING.md für die Einrichtung einer Entwicklungsumgebung und das Ausführen der Testsuite ohne einen echten Exchange-Server. Für Sicherheitsmeldungen siehe SECURITY.md.

Lizenz

MIT — siehe LICENSE.