email-mcp

E-Mail + Kalender über klassisches Outlook unter Windows, gesteuert über natives COM (pywin32). Wird als einzelner email-Befehl ausgeliefert, der sowohl eine CLI als auch ein stdio-MCP-Server ist. Keine Azure-App-Registrierung, kein OAuth, kein PowerShell — er steuert einfach den Outlook-Desktopclient, bei dem Sie bereits angemeldet sind.

Voraussetzungen

• Windows 10/11

• Klassischer Outlook-Desktopclient, konfiguriert mit mindestens einem Konto

• Python 3.10+ und uv

Die „neue“ Outlook-Version für Windows stellt kein COM bereit. Wenn Sie die neue Outlook-Version verwenden und nicht zurück zur klassischen Version wechseln können, funktioniert dies nicht für Sie.

COM wird nur über den Outlook-Desktopclient erreicht — es gibt ekeine separate Authentifizierung. Welches Konto auch immer in Outlook angemeldet ist, genau das sieht das Tool, und gesendete E-Mails landen im echten Gesendet-Ordner, genau als hätten Sie sie per Hand gesendet.

Related MCP server: outlook-mcp

Installieren / Ausführen

Direkt von GitHub mit uvx ausführen (kein Klonen, keine manuelle Installation):

uvx --from git+https://github.com/kerodkibatu/email-mcp email --help

uv löst das Paket beim ersten Start zur Laufzeit auf und legt einen Cache an; spätere Aufrufe sind schnell.

CLI

Jedes Tool ist ein Unterbefehl von email. Ausgegeben wird JSON auf stdout.

# List configured Outlook accounts
uvx --from git+https://github.com/kerodkibatu/email-mcp email list-accounts

# Query across all mail folders with a MongoDB-style filter (JSON string)
uvx --from git+https://github.com/kerodkibatu/email-mcp email query \
  --filter '{"$and":[{"from":{"$contains":"@kyros.com"}},{"unread":true}]}' \
  --limit 20 --order-by received_desc

# Read one email by EntryID
uvx --from git+https://github.com/kerodkibatu/email-mcp email read --entry-id "0000000..."

# Send a new mail (account is REQUIRED — see below)
uvx --from git+https://github.com/kerodkibatu/email-mcp email send \
  --to client@example.com \
  --subject "Status update" \
  --body "Heads up — ..." \
  --account kerod@towlydigital.com

# Save a new mail as a draft instead of sending (same flags as send, no --send-as)
uvx --from git+https://github.com/kerodkibatu/email-mcp email draft \
  --to client@example.com \
  --subject "Status update" \
  --body "Heads up — ..." \
  --account kerod@towlydigital.com

MCP

email mcp startet einen stdio-MCP-Server, der alle 11 Tools bereitstellt. Fügen Sie ihn zu Ihrer .mcp.json (oder claude_desktop_config.json) hinzu:

{
  "mcpServers": {
    "email": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kerodkibatu/email-mcp", "email", "mcp"]
    }
  }
}

Der erste Start dauert etwas länger, währ des Pakets auflöst; spätere Starts greifen auf den Cache zu.

Tools

Auswahl des sendenden Kontos

send_email, reply_email und forward_email erfordern einen account-Parameter — einen Teilstring des konfigurierten Outlook-Kontonamens (typischerweise die SMTP-Adresse). Das ist beabsichtigt: Sind mehrere Konten konfiguriert (z. B. privat + beruflich), ist das automatische Fallen auf Outlooks primäres Konto ein Stolperstein — auf diese Weise kann private E-Mail über ein Arbeitskonto oder umgekehrt verschickt werden. Wenn der Aufrufer das Konto explizit benennen muss, wird das Senden eindeutig không.

Wenn der angegebene account mit keinem konfigurierten Konto übereinstimmt (Teilstring, Groß-/Kleinschreibung wird nicht beachtet), meldet das Tool einen Fehler und listet die verfügbaren Konten auf. Führen Sie zuerst list_accounts aus, falls Sie den Namen noch nicht kennen. Das Transportkonto wird direkt auf dem Outlook-Element über SendUsingAccount gesetzt.

{
  "to": "client@example.com",
  "subject": "Status update",
  "body": "Heads up — ...",
  "account": "kerod@towlydigital.com"
}

Send As (EXPERIMENTELL — Exchange-Berechtigung „Send As“ erforderlich)

EXPERIMENTELL. Dieser Weg steuert klassisches Outlook ausschließlich über pywin32-COM — es gibt keinen Azure/OAuth-Pfad. Das Verhalten d von der Mandatsrichtlinie ab, und er kann abgelehnt, stillschweigend hinabgestuft oder im Postausgang liegen bleiben. Begreifen Sie es als Best-Effort.

send_email, reply_email und forward_email akzeptieren einen optionalen Parameter send_as — eine SMTP-Adresse, „als die“ der senden. Für den Empfänger erscheint diese Adresse als Absender, ohne einen Hinweis „im Auftrag von“. Es handelt sich um echtes Exchange-Send-As, im Gegensatz zu Send on Giveventil.

Mechanisch setzen das Tool SendUsingAccount auf das angegebene account (das Transportpostfach), löst dann send_as gegen Exchange auf und überschreibt vor dem Absenden sowohl PR_SENT_REPRESENTING_* als auch PR_SENDER_* MAPI-Eigenschaften (über den PropertyAccessor des Elements), sodass sie daran die Adresse verweisen. Das Überschreiben der Absender-Eigenschaften — nicht nur der Representing-Eigenschaften — ist der Punkt, der aus „im Auftrag“ ein reines Send-As macht. Exchange validiert die Berechtigung zum Zeitpunkt der Übermittlung.

Anforderungen:

• Der account-Benutzer muss die Send-As-Berechtigung für das send_as-Postfach besitpassen, serverseitig erteilt von einem Exchange-Administrator. Das Tool kann die Berechtigung weder erteilen noch prüfen — es kann den Sendotbestand ja nicht prüfen

• Die send_as-Adresse muss von Exchange auflösbar sein — typischerweise ein Postbesiegenfach im gleichen Mandanten. Externe Adressen (gmail.com usw.) werden bei der Auflösung einen Fehler liefern.

• Fehlt die Berechtigung, hängt das Verhalten von der Mandantenrichtlinie ab: Exchange kann die Nachricht zurückweisen, sie stillschweigend zu „im Auftrag von“ herabstufen oder im Outbox liegen lassen.

• Diese Funktion funktioniert nur innerhalb einer Exchange-Organisation, die sie ausdrücklich erlaubt hat. Damit kann man nicht externeArgender vorspiegeln.

{
  "to": "client@example.com",
  "subject": "Status update",
  "body": "Heads up — ...",
  "account": "admin@custom.com",
  "send_as": "contact@custom.com"
}

Die Antwort enthält ein sent_as-Feld, das die Adresse zurückgibt, wenn send_as verwendet wird.

Anhänge senden

Anhänge senden

send_email akzeptiert ein optionales attachments-Array mit absoluten Dateipfaden. Jeder Pfad muss existieren und auf eine Hauptdatei verweisen; falls ein Pfad ungültig ist, liefert das Tool einen Fehler und listet die betroffenen Pfade auf — es wird keine E-Mail gesendet. Unter Windows werden vorwärts und umgekehrte Slaquests gleichermaßen akzeptYet; ~ und Umgebungsvariablen werden nicht expandiert — senden Sie vollständig aufgelöste Pfade.

{
  "to": "kerod@example.com",
  "subject": "Signed contract",
  "body": "See attached.",
  "account": "kerod@towlydigital.com",
  "attachments": [
    "C:\\Users\\Kerod\\Desktop\\contract.pdf",
    "C:/Users/Kerod/Desktop/cover-letter.pdf"
  ]
}

Anhänge herunterladen

download_attachments extrahiert Dateien aus einer E-Mail, speichert sie lokal und gibt den absoluten Ordnerpfad return.

• Speicherort: Dateien werden im Downloads-Ordner des Benutzers gespeichert: ~/Downloads/email-attachments/YYYY-MM-DD_sender-slug_subject-slug/.

• Inline-Bilder: Logos" und Signaturbilder werden standardmäßig herausgefiltert, um keine Unordnung zu erzeugen. Setzen Sie include_inline: true, falls Sie sie speziell benötigen.

• Idempotenz: Ein erneutes Ausführen des Tools für dieselbe E-Mail verwendet denselben Ordner (über eine .entry_id-Markierung bewache, sicher) und ergibt die Identifizierung, wenn zwei unterschiedliche E-Mails auf denselben Namen kommen.

So funktioniert

Der Befehl email stellt per COM eine Verbindung zu einer laufenden Outlook-Instanz her (fällt falls er auf Spring es, falls keine läuft) und arbeitet den MAPI-Namespace, um E-Mails zu lesen und zu schreiben. Der gesamte COM-Zugriff läuft über eine einzige Outlook-Sitzung; das Tool startet niemals PowerShell.

Das betrifft:

• Outlook muss installiert sein (es muss nicht geöffnet sein — der erste Aufruf startet es)

• Das Konto, das in Outlook angemeldet ist, ist genau das, wie vom Tool gesehen wird — keine gesonderte Authentifizierung

• Gesendete Mails erscheint im Sent-Folder des Benutzers genau so, als wären sie manuell gesendet worden

Lizenz

MIT — siehe LICENSE.