mcp-outlook

Ein selbst hostbarer MCP-Server für lokales Microsoft Exchange über EWS (Exchange Web Services). Entwickelt für Air-Gap-/Cloud-freie Umgebungen – er spricht direkt mit Ihrem internen Exchange-Server und berührt niemals Microsoft Graph, Azure AD oder einen Outlook-Desktop-Client.

• Backend: exchangelib (EWS-Client)

• Framework: FastMCP

• Transport: streamable-http (ein eigenständiger HTTP-Server, mit dem sich andere interne Hosts verbinden)

• Authentifizierung bei Exchange: Basic oder NTLM (per Konfiguration wählbar)

Zwei Modi

Wie der jwt- Modus Identitäten überbrückt. Exchange kann Ihre Unternehmens-JWTs nicht verarbeiten (Outlook basiert auf PKINIT/Kerberos). Der MCP führt daher zwei getrennte Authentifizierungen durch, die niemals vermischt werden:

User --(JWT)--> MCP validates the token, reads the user's email
                MCP --(service account, NTLM)--> Exchange
                MCP --(impersonation header = user's email)--> acts on the user's mailbox

Das Benutzer-JWT wird niemals an Exchange gesendet, und kein Benutzerpasswort und keine Smartcard berührt jemals den MCP – nur die einzelne Dienstkonto-Anmeldeinformation. Siehe TODO.md für das, was Administratoren für den jwt-Modus einrichten müssen.

Related MCP server: OWA Exchange MCP Server

Tools

list_emails und search_emails akzeptieren außerdem unread_only=true, um nur ungelesene Nachrichten zurückzugeben.

Einrichtung

Erfordert Python 3.11+ und uv.

uv sync                 # create venv + install deps
cp .env.example .env    # then edit .env with your Exchange details
uv run python -m mcp_outlook

Der Server bindet an MCP_HOST:MCP_PORT (Standard 127.0.0.1:8000) und stellt den streamable-http-MCP-Endpunkt unter /mcp bereit.

Lokale Beta-Tests (keine Admin-Einrichtung erforderlich)

Führen Sie ihn gegen Ihr eigenes Postfach mit Ihrem eigenen Benutzernamen/Passwort aus – kein JWT, keine Impersonation, kein Dienstkonto, keine Smartcard:

# in .env:
OUTLOOK_AUTH_MODE=static          # the default
OUTLOOK_EWS_ENDPOINT=https://mail.corp.local/EWS/Exchange.asmx
OUTLOOK_USERNAME=CORP\you
OUTLOOK_PASSWORD=...
uv run python -m mcp_outlook

Konfiguration

Alle Einstellungen stammen aus Umgebungsvariablen (oder einer .env-Datei). Die vollständige Liste finden Sie in .env.example. Die wichtigsten:

So finden Sie Ihren EWS-Endpunkt

Die EWS-URL ist nicht die OWA-URL (Webmail). Auf dem Exchange-Server:

Get-WebServicesVirtualDirectory | fl Name,InternalUrl,ExternalUrl

In einer Air-Gap-Umgebung möchten Sie fast immer die InternalUrl.

Testen

Unit-Tests benötigen keinen Exchange-Server (nur Konfigurations-Parsing + Serialisierung):

uv run pytest

Live-Smoke-Test (mit einer echten .env): Server starten, einen MCP-Client oder den MCP Inspector verbinden, dann list_folders → list_emails → send_email (an sich selbst) aufrufen und den Empfang bestätigen. Stellen Sie OUTLOOK_AUTH_TYPE zwischen ntlm und basic um, um zu bestätigen, welche Variante Ihr Exchange-Administrator aktiviert hat.

Compose-UI (MCP Apps)

draft_email öffnet ein interaktives MCP Apps-Widget – einen React-Composer, der in eine einzelne eigenständige HTML-Datei (src/mcp_outlook/widgets/compose.html) eingebettet ist. Jeder Host mit MCP-Apps-Unterstützung rendert es inline im Chat-Verlauf.

Widget-Funktionen:

• An-Feld mit Inline-Kontaktsuche – Nach dem letzten Komma tippen, um Kontakte zu suchen; ein Ergebnis auswählen, um die Abfrage durch einen Chip zu ersetzen; gültige Adressen werden als beschriftete Chips dargestellt.

• Senden / Verwerfen – Senden löst send_email direkt aus dem Widget aus (nur für Apps – das Modell kann es nicht aufrufen); Verwerfen klappt die Karte zusammen.

• Ersetzung – Beim Öffnen eines neuen Entwurfs wird jedes ältere geöffnete Entwurfs-Widget ausgegraut.

• Signatur – Jeder Entwurf ist mit „Written with Airchat“ vorausgefüllt (bearbeitbar).

Air-Gap-Garantie: Das gebaute HTML (React + Bridge-JS inline) wird mit dem Python-Paket ausgeliefert. Zur Laufzeit werden keine externen Ressourcen angefordert; Node.js wird nur zum Neuerstellen des Widgets benötigt.

Widget neu erstellen (nur Entwicklung)

cd frontend
npm ci
npm run build     # tsc + vite build + artifact copy → src/mcp_outlook/widgets/compose.html

Das Build-Skript prüft, bevor es kopiert, dass keine externen URLs in das HTML gelangt sind.

Visuell ausprobieren (eigenständige Entwicklervorschau)

cd frontend && npm run dev
# Opens http://localhost:5173 with a mock host — no Exchange needed.
# Type in To, see chips form, contact results appear, Send/Discard collapse the card.

Stolperfallen

• Basic-Auth ist auf modernen Exchange-Servern oft deaktiviert – NTLM ist die sicherere Standardwahl.

• Interne/selbstsignierte Zertifikate erfordern OUTLOOK_CA_BUNDLE, andernfalls schlägt die Verbindung bei der TLS-Verifizierung fehl.

• Der Mehrbenutzermodus (jwt) benötigt eine Exchange-Berechtigung – das Dienstkonto muss über die RBAC-Rolle ApplicationImpersonation verfügen. Siehe TODO.md. Der static- Modus benöticht keine solche Berechtigung.

• .env enthält ein Klartext-Passwort. Sie ist git-ignoriert; schränken Sie außerdem die Dateiberechtigungen (chmod 600 .env) auf dem Host ein.