maildoc

Leichtgewichtige E-Mail-Suche, Anhang-Abruf und PDF-Extraktionstools für KI-Agenten und Automatisierung.

Einrichtung

pip install -r requirements.txt

Legen Sie Anmeldedaten in .env fest (siehe .env.example):

GMAIL_USERNAME=user@example.com
GMAIL_APP_PASSWORD=your_app_password

Schnellstart

from maildoc import search_emails, download_attachment, extract_pdf_text

# Search emails with attachments
emails = search_emails(
    sender="billing@example.com",
    with_attachments=True,
    limit=5,
)

# Download and extract text from PDF attachments (with optional password for protected files)
for email in emails:
    for att in email["attachments"]:
        if att["filename"].endswith(".pdf"):
            pdf_bytes = download_attachment(email["uid"], att["filename"])
            if pdf_bytes:
                # Pass password if the PDF is password-protected (e.g., bank statements)
                text = extract_pdf_text(pdf_bytes, password="optional_password")
                print(text)

MCP-Server (Claude Desktop / Cursor / Antigravity)

Als Model Context Protocol (MCP)-Server ausführen:

python server.py

Beispiel claude_desktop_config.json:

{
  "mcpServers": {
    "maildoc": {
      "command": "python",
      "args": ["/absolute/path/to/maildoc/server.py"],
      "env": {
        "GMAIL_USERNAME": "user@example.com",
        "GMAIL_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

Tool-Referenz

E-Mail & Suche

• search_emails(sender, subject, body, seen, date_gte, date_lt, with_attachments, folder, limit): Durchsucht das Postfach und gibt strukturierte Dicts zurück.

• fetch_email_by_uid(uid, folder): Ruft eine einzelne E-Mail anhand der UID ab.

• list_folders(): Listet die Postfach-Ordner auf.

• mark_email_as_read(uid, folder): Markiert die E-Mail als gelesen.

• move_email(uid, destination_folder, source_folder): Verschiebt die E-Mail zwischen Ordnern.

• delete_email(uid, folder): Löscht die E-Mail.

• create_folder(folder_name): Erstellt einen Postfach-Ordner.

• delete_folder(folder_name): Löscht einen Postfach-Ordner.

• connect_to_email(), disconnect_from_email(): Hilfsfunktionen für den Verbindungslebenszyklus.

PDF-Extraktion

• read_pdf_attachment(uid, attachment_filename, password=None, folder="INBOX"): Lädt den Anhang herunter und extrahiert dessen Text direkt in einem Schritt (ideal für MCP / KI-Agenten).

• extract_pdf_text(pdf_bytes, password=None): Extrahiert den gesamten Text aus PDF-Bytes.

• extract_pdf_page_text(pdf_bytes, page_number, password=None): Extrahiert Text aus einer bestimmten Seite (1-basiert).