useful-outlook-mcp

Ein Remote-MCP-Server für Microsoft Outlook mit korrektem OAuth2 und agentenoptimierten Tools.

Funktionen

• Spezifikationskonform: OAuth-Metadaten gemäß RFC 9728/8414, dynamische Client-Registrierung gemäß RFC 7591

• Zustandsloses OAuth: Tokens werden vom Client verwaltet, nicht vom Server – so wie es OAuth vorsieht

• Agentenoptimierte Tools: Umfangreiches Prompt-Engineering in den Tool-Beschreibungen

• Dynamische Scopes: OAuth-Scopes passen sich automatisch an die aktivierten Tools an

• Produktionsreif: Docker, Rate-Limiting, Read-only-Modus, Tool-Filterung

Related MCP server: M365 MCP Server

Schnellstart

npm install
npm run build
npm start  # Server at http://localhost:3000

Erforderliche Umgebung:

MS365_MCP_CLIENT_ID=your-azure-ad-client-id
MS365_MCP_CLIENT_SECRET=your-azure-ad-client-secret
MS365_MCP_TENANT_ID=your-tenant-id  # or 'common'

Azure-AD-Einrichtung

1. Azure Portal → Microsoft Entra ID → App-Registrierungen → Neu

2. Fügen Sie delegierte Berechtigungen hinzu: User.Read, Mail.Read, Mail.ReadWrite, Mail.Send, Calendars.Read, Calendars.ReadWrite, Calendars.Read.Shared, Place.Read.All, People.Read, offline_access

3. Fügen Sie eine Redirect-URI hinzu: http://localhost:6274/oauth/callback (für MCP Inspector)

4. Zertifikate & Geheimnisse → Neues Client-Geheimnis → Wert kopieren

5. Kopieren Sie Client-ID, Client-Geheimnis und Mandanten-ID in Ihre .env.

Tools

E-Mail

list-mail-folders · list-mail-messages · search-mail · get-mail-message · send-mail · create-draft-mail · reply-mail · reply-all-mail · create-reply-draft · create-reply-all-draft · delete-mail-message · move-mail-message

Kalender

list-calendars · list-calendar-events · search-calendar-events · find-meeting-times · get-calendar-event · get-calendar-view · create-calendar-event · update-calendar-event · delete-calendar-event

Personen

lookup-contact-email

Raumsuche

Für Präsenzbesprechungen fürt find-meeting-times automatisch Folgendes aus:

• Ruft alle verfügbaren Besprechungsräume in Ihrer Organisation ab

• Bezieht sie neben den Teilnehmern in die Verfügbarkeitsprüfung ein

• Gruppiert freie Räume nach Standort (Stadt/Gebäude)

• Gibt nur verfügbare Räume mit E-Mail-Adressen zur Buchung zurück

Setzen Sie isOnlineMeeting: false, um die Raumsuche zu aktiieren. Für Online-Besprechungen (Standard: true) wird automatisch ein Teams-Besprechungslink generiert.

Erforderlicher Scope: Place.Read.All (zu den Berechtigungen der Azure-AD-App hinzufügen)

Konfiguration

Docker

Aus der GitHub Container Registry:

docker run -p 3000:3000 \
  -e MS365_MCP_CLIENT_ID=xxx \
  -e MS365_MCP_CLIENT_SECRET=xxx \
  -e MS365_MCP_TENANT_ID=xxx \
  ghcr.io/Leonine-Studios/useful-outlook-mcp:latest

Oder lokal erstellen:

docker build -t useful-outlook-mcp .
docker run -p 3000:3000 \
  -e MS365_MCP_CLIENT_ID=xxx \
  -e MS365_MCP_CLIENT_SECRET=xxx \
  -e MS365_MCP_TENANT_ID=xxx \
  useful-outlook-mcp

Endpunkte

Tests

npm run dev
npx @modelcontextprotocol/inspector  # Connect to http://localhost:3000/mcp

Hinweise zum Design

Probleme mit bestehenden Servern

1. Legacy-Architektur: Als stdio mit nachträglich aufgesetztem HTTP gebaut. Dieser Server ist HTTP-nativ.

2. OAuth falsch umgesetzt: Die meisten Server speichern Tokens serverseitig. Dieser Server ist zustandslos – Tokens werden pro Anfrage über den Authorization-Header übergeben und nie gespeichert.

3. Tools ohne Konzept: Typische Server bilden API-Endpunkte 1:1 ohne Hilfestellung ab. Agenten scheitern im praktischen Einsatz, weil sie API-Eigenheiten oder mehrstufige Workflows nicht kennen.

Was ist anders?

Jedes Tool enthält:

• Wann man es im Vergleich zu Alternativen verwendet

• Bekannte Eingenheiten der Graph API (es gibt viele)

• Workflow-Anleitung für mehrstufige Aufgaben

• Parameterkombinationen, die zu Fehlern führen

Beispiel: find-meeting-times erklärt, dass E-Mail-Adressen erforderlich sind (Namen funktionieren nicht), wie man über search-mail E-Mail-Adressen aus Namen ermittelt, was OrganizerUnavailable bedeutet und dass isOrganizerOptional=true eine Benutzerbestätigung erfordert.

Bekannte Eigenheiten der Graph API

• E-Mail-Absenderfilterung: eq auf from/emailAddress/address ist unzuverlässig – startswith() verwenden

• E-Mail-Empfängerfilterung: Mit $filter kann nicht nach An/CC/BCC gefiltert werden – $search muss verwendet werden

• Kalender-Organisatorfilterung: $filter auf die Organisator-E-Mail-Adresse liefert 500 – clientseitig gefiltert

• Nebenläufigkeit: Parallele Aufrufe können MailboxConcurrency-Fehler zurückgeben

• Suche + Sortierung: $search kann nicht mit $orderby kombiniert werden

Linzenz

MIT