E-Mail-MCP-Server

Ein Model Context Protocol (MCP)-Server, der E-Mail-Zugriff über IMAP und SMTP bereitstellt. Ermöglicht KI-Agenten und Anwendungen das Lesen, Suchen, Senden und Verwalten von E-Mails über eine standardisierte HTTP/SSE-Schnittstelle.

Funktionen

• 9 E-Mail-Tools via MCP:

  • list_folders - Alle IMAP-Postfächer/Ordner auflisten

  • search_emails - E-Mails mit Filtern suchen (Absender, Betreff, Datumsbereich, Status gelesen/markiert)

  • read_email - Vollständigen E-Mail-Inhalt abrufen, einschließlich Textkörper und Anhang-Metadaten

  • mark_email - E-Mails als gelesen/ungelesen oder markiert/nicht markiert kennzeichnen

  • move_email - E-Mails zwischen Ordnern verschieben

  • send_email - Neue E-Mails senden (Nur-Text oder Multipart-HTML)

  • reply_email - Auf E-Mails antworten unter Beibehaltung der Thread-Header

  • download_attachment - E-Mail-Anhänge in das Arbeitsverzeichnis herunterladen

  • send_email_with_attachments - E-Mails mit Dateianhängen aus dem Arbeitsverzeichnis senden

• Produktionsreife Architektur:

  • Async-natives IMAP/SMTP mit Verbindungspooling

  • Pydantic-basierte Konfiguration und Validierung

  • Umfassende Fehlerbehandlung mit strukturierten Exceptions

  • API-Key-Authentifizierung via X-API-Key-Header

  • systemd-Service-Datei für Ubuntu-Bereitstellung

• Testgetriebene Entwicklung:

  • 85+ Unit- und Integrationstests

  • 100% Abdeckung der Kernfunktionalität

  • Gemockte E-Mail-Server für reproduzierbare Tests

Installation mit Claude Desktop (Empfohlen)

Der einfachste Weg, diesen Server zu nutzen, ist über das MCPB-Bundle — eine Einzeldatei-Installation für Claude Desktop.

1. Herunterladen

Laden Sie email_mcp.mcpb von der neuesten Version herunter.

2. Installieren

Doppelklicken Sie auf email_mcp.mcpb. Claude Desktop öffnet einen Installationsdialog.

3. Konfigurieren

Geben Sie bei Aufforderung Ihre Mailserver-Anmeldedaten ein. Alle Werte werden im OS-Schlüsselbund gespeichert (macOS Keychain / Linux Secret Service):

Gmail-Nutzer: Sie müssen ein App-Passwort verwenden, nicht Ihr reguläres Google-Konto-Passwort. Aktivieren Sie IMAP unter Gmail-Einstellungen → Weiterleitung und POP/IMAP.

4. Verwenden

Sobald die Installation abgeschlossen ist, kann Claude auf Ihre E-Mails zugreifen. Versuchen Sie:

"Liste meine ungelesenen E-Mails von dieser Woche auf" "Suche nach E-Mails von alice@example.com bezüglich des Projekts" "Sende eine E-Mail an bob@example.com mit dem Betreff 'Hallo' und dem Text 'Hi Bob!'" "Lade den ersten Anhang der E-Mail mit UID 12345 herunter" "Sende eine E-Mail mit dem Anhang report.pdf an team@example.com"

Anforderungen

• Python 3.10+ (3.13 empfohlen)

• IMAP- und SMTP-Serverzugriff

• API-Key für MCP-Authentifizierung

Schnellstart

1. Klonen und Einrichten

git clone https://github.com/pzanna/email_mcp.git
cd email_mcp
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Umgebung konfigurieren

cp .env.example .env
# Edit .env with your credentials

Erforderliche Umgebungsvariablen:

# IMAP Configuration
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=you@gmail.com
IMAP_PASSWORD=your-app-password
IMAP_SSL=true

# SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@gmail.com
SMTP_PASSWORD=your-app-password
# SMTP_STARTTLS mode: "none" (auto), "true" (force), "false" (disable)
SMTP_STARTTLS=true

# MCP Server Configuration
MCP_API_KEY=your-secret-api-key-here
MCP_HOST=127.0.0.1
MCP_PORT=8420
MCP_SERVER_NAME=email-mcp
MCP_BASE_URL=http://localhost:8420

# Optional
DEFAULT_FROM_NAME=Your Name
MAX_SEARCH_RESULTS=50
IMAP_POOL_SIZE=3

# Attachment Configuration
EMAIL_BASE_DIR=/path/to/workspace
MAX_ATTACHMENT_SIZE_MB=50

3. Server ausführen

Lokale Entwicklung (Mac/Linux):

source .venv/bin/activate
uvicorn main:app --host 127.0.0.1 --port 8420

Zugriff auf den Server:

• MCP-Endpunkt: http://localhost:8420/mcp

• Gesundheitsprüfung: http://localhost:8420/health

• API-Dokumentation: http://localhost:8420/docs

Testen

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=. --cov-report=html

# Run specific test file
pytest tests/test_integration.py -v

# Run specific test
pytest tests/test_send.py::test_send_email_plain_text -v

Alle 85+ Tests sollten erfolgreich durchlaufen.

Anwendungsbeispiele

Authentifizierung

Alle MCP-Endpunkte erfordern den X-API-Key-Header:

curl -H "X-API-Key: your-secret-api-key-here" \
  http://localhost:8420/mcp/tools

Verfügbare Tools auflisten

curl -X GET http://localhost:8420/mcp/tools \
  -H "X-API-Key: your-secret-api-key-here"

E-Mails suchen

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "search_emails",
      "arguments": {
        "from": "user@example.com",
        "subject": "invoice",
        "since": "2024-01-01",
        "limit": 10
      }
    }
  }'

E-Mail senden

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "send_email",
      "arguments": {
        "to": ["recipient@example.com"],
        "subject": "Test Email",
        "body": "This is a test email.",
        "from_name": "My Name"
      }
    }
  }'

E-Mail lesen

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "read_email",
      "arguments": {
        "uid": "12345",
        "folder": "INBOX"
      }
    }
  }'

E-Mail-Anhang herunterladen

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "download_attachment",
      "arguments": {
        "uid": "12345",
        "attachment_index": 0,
        "folder": "INBOX",
        "filename_override": "renamed_file.pdf"
      }
    }
  }'

Lädt den Anhang in EMAIL_BASE_DIR/attachments/email/downloads/ herunter, mit Sicherheitsvalidierung, um sicherzustellen, dass Dateien innerhalb des Basisverzeichnisses bleiben.

E-Mail mit Anhängen senden

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "send_email_with_attachments",
      "arguments": {
        "to": ["recipient@example.com"],
        "cc": ["manager@example.com"],
        "subject": "Monthly Report",
        "body": "Please find the reports attached.",
        "body_html": "<p>Please find the <strong>reports</strong> attached.</p>",
        "from_name": "John Doe",
        "attachment_paths": [
          "attachments/email/uploads/report1.pdf",
          "attachments/email/uploads/report2.xlsx"
        ]
      }
    }
  }'

Hängt Dateien aus dem Arbeitsverzeichnis an, mit vollständiger Sicherheitsvalidierung und Durchsetzung von Größenbeschränkungen.

Umgang mit Anhängen

Der E-Mail-MCP-Server bietet eine sichere Handhabung von Anhängen mit arbeitsverzeichnisbasierter Dateiverwaltung.

Struktur des Arbeitsverzeichnisses

Alle Anhang-Operationen sind auf das konfigurierte Arbeitsverzeichnis beschränkt:

EMAIL_BASE_DIR/
└── attachments/
    └── email/
        ├── downloads/    # Downloaded email attachments
        └── uploads/      # Files ready to attach to outgoing emails

Sicherheitsfunktionen

• Arbeitsverzeichnis-Einschränkung: Alle Dateioperationen sind auf EMAIL_BASE_DIR beschränkt

• Schutz vor Pfad-Traversal: Verhindert den Zugriff auf Dateien außerhalb des Arbeitsverzeichnisses

• Dateinamen-Sanitierung: Entfernt gefährliche Zeichen und behandelt reservierte Namen

• Größenbeschränkungen: Konfigurierbare Limits pro Datei und für die Gesamtgröße der Anhänge

• Dateityp-Validierung: Stellt sicher, dass Anhang-Pfade auf tatsächliche Dateien zeigen

Workflow-Beispiele

Download → Senden-Workflow:

1. Verwenden Sie download_attachment, um E-Mail-Anhänge in downloads/ zu speichern

2. Verschieben oder kopieren Sie Dateien bei Bedarf nach uploads/

3. Verwenden Sie send_email_with_attachments, um Dateien aus uploads/ zu senden

Direkter Upload-Workflow:

1. Legen Sie Dateien im Verzeichnis uploads/ ab

2. Verwenden Sie send_email_with_attachments mit arbeitsverzeichnis-relativen Pfaden

Konfiguration

# Workspace directory (required for attachment operations)
EMAIL_BASE_DIR=/path/to/your/workspace

# Maximum attachment size per file (default: 50MB)
MAX_ATTACHMENT_SIZE_MB=50

Bereitstellung

Ubuntu-Server mit systemd

1. Dateien auf den Server kopieren:

scp -r email_mcp user@server:/home/user/

1. Python-Umgebung einrichten:

ssh user@server
cd ~/email_mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

1. Für Fernzugriff konfigurieren: Bearbeiten Sie .env:

MCP_HOST=0.0.0.0  # Allow remote connections
MCP_BASE_URL=http://<your-server-ip>:8420  # Your server IP

1. systemd-Service installieren:

# Edit email-mcp.service to match your paths
sudo cp email-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable email-mcp
sudo systemctl start email-mcp

1. Status prüfen:

sudo systemctl status email-mcp
sudo journalctl -u email-mcp -f  # View logs

MCP-Client konfigurieren

Fügen Sie dies zu Ihrer MCP-Client-Konfiguration hinzu:

{
  "mcpServers": {
    "email": {
      "url": "http://localhost:8420/mcp",
      "headers": {
        "X-API-Key": "your-secret-api-key-here"
      }
    }
  }
}

Für einen Remote-Server verwenden Sie http://<ihre-server-ip>:8420/mcp (ersetzen Sie dies durch Ihre Server-IP).

Architektur

email_mcp/
├── main.py                 # FastAPI application entry point (HTTP/SSE mode)
├── mcp_server.py           # Stdio MCP entry point (MCPB / Claude Desktop mode)
├── config.py               # Pydantic settings (env vars)
├── auth.py                 # API key authentication middleware
├── imap/
│   ├── client.py          # IMAP connection pool
│   ├── read.py            # list_folders, read_email
│   ├── search.py          # search_emails
│   ├── flags.py           # mark_email, move_email
│   └── attachments.py     # download_attachment
├── smtp/
│   ├── client.py          # send_email, reply_email
│   └── attachments.py     # send_email_with_attachments
├── tools/
│   ├── definitions.py     # MCP tool schemas
│   ├── handlers.py        # Tool request routing
│   └── mcp_routes.py      # MCP HTTP endpoints
├── utils/
│   └── attachment_utils.py # Secure file handling utilities
└── tests/                  # 85+ unit and integration tests

Wichtige Designmuster

• Verbindungspooling: asyncio.Semaphore begrenzt gleichzeitige IMAP-Verbindungen (Standard: 3)

• Fehlerbehandlung: Strukturierte Exceptions werden auf MCP-Fehlerantworten abgebildet

• E-Mail-Threading: In-Reply-To- und References-Header für Antwortketten

• Multipart-Nachrichten: Durchlaufen des Nachrichtenbaums zum Extrahieren von Text/HTML/Anhängen

• Keine Binärübertragung: Anhänge geben nur Metadaten zurück (Dateiname, Größe, content_type)

Fehlerbehebung

Gmail-spezifische Einrichtung

1. IMAP aktivieren: Einstellungen → Weiterleitung und POP/IMAP → IMAP aktivieren

2. App-Passwort: Verwenden Sie ein App-Passwort anstelle Ihres regulären Passworts

3. Gmail SMTP: Verwenden Sie smtp.gmail.com:587 mit STARTTLS

Verbindungsprobleme

# Test IMAP connection
openssl s_client -connect imap.gmail.com:993

# Test SMTP connection
openssl s_client -starttls smtp -connect smtp.gmail.com:587

Häufige Fehler

• CONNECTION_TIMEOUT: Überprüfen Sie IMAP_HOST und IMAP_PORT

• AUTH_FAILED: Überprüfen Sie die Anmeldedaten, verwenden Sie ein App-Passwort für Gmail

• FOLDER_NOT_FOUND: Ordnernamen unterscheiden zwischen Groß- und Kleinschreibung (verwenden Sie list_folders zur Überprüfung)

• MESSAGE_NOT_FOUND: UID ist möglicherweise ungültig oder die Nachricht wurde gelöscht

SMTPException - Connection already using TLS: Setzen Sie SMTP_STARTTLS=none in .env für den Auto-Modus. Gültige Werte sind none, true und false.

Entwicklung

Projektstruktur

• imap/ - IMAP-Client und Tools (lesen, suchen, Flags)

• smtp/ - SMTP-Client und Tools (senden, antworten)

• tools/ - MCP-Endpunkt-Handler und Schemas

• tests/ - Unit- und Integrationstests

Ausführung in der Entwicklung

# Auto-reload on file changes
uvicorn main:app --reload --host 127.0.0.1 --port 8420

# Debug mode with verbose logging
LOG_LEVEL=DEBUG uvicorn main:app --host 127.0.0.1 --port 8420

Neue Tools hinzufügen

1. Definieren Sie Pydantic-Modelle für Ein-/Ausgabe im entsprechenden Modul

2. Implementieren Sie die asynchrone Funktion mit Fehlerbehandlung

3. Fügen Sie das Tool-Schema zu tools/definitions.py hinzu

4. Binden Sie den Dispatcher in tools/mcp_routes.py ein

5. Schreiben Sie Tests gemäß dem TDD-Ansatz

Lizenz

MIT

Mitwirken

Beiträge sind willkommen! Bitte:

1. Schreiben Sie Tests für alle neuen Funktionen

2. Folgen Sie dem bestehenden Code-Stil (black, isort, mypy)

3. Aktualisieren Sie diese README bei wesentlichen Änderungen

4. Stellen Sie sicher, dass alle Tests bestehen, bevor Sie PRs einreichen

Support

Für Probleme, Fragen oder Funktionsanfragen öffnen Sie bitte ein Issue auf GitHub.