maildoc

Lightweight email search, attachment retrieval, and PDF extraction tools for AI agents and automation.

Setup

pip install -r requirements.txt

Set credentials in .env (see .env.example):

GMAIL_USERNAME=user@example.com
GMAIL_APP_PASSWORD=your_app_password

Quickstart

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)

Run as a Model Context Protocol (MCP) server:

python server.py

Example 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"
      }
    }
  }
}

Tools Reference

Email & Search

• search_emails(sender, subject, body, seen, date_gte, date_lt, with_attachments, folder, limit): Search mailbox and return structured dicts.

• fetch_email_by_uid(uid, folder): Fetch a single email by UID.

• list_folders(): List mailbox folders.

• mark_email_as_read(uid, folder): Mark email as read.

• move_email(uid, destination_folder, source_folder): Move email between folders.

• delete_email(uid, folder): Delete email.

• create_folder(folder_name): Create mailbox folder.

• delete_folder(folder_name): Delete mailbox folder.

• connect_to_email(), disconnect_from_email(): Connection lifecycle helpers.

PDF Extraction

• read_pdf_attachment(uid, attachment_filename, password=None, folder="INBOX"): Download attachment and extract its text directly in one step (ideal for MCP / AI agents).

• extract_pdf_text(pdf_bytes, password=None): Extract all text from PDF bytes.

• extract_pdf_page_text(pdf_bytes, page_number, password=None): Extract text from a specific page (1-indexed).