pip install -r requirements.txt

GMAIL_USERNAME=user@example.com
GMAIL_APP_PASSWORD=your_app_password

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)

python server.py

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

Wait, I need to double-check the "1-indexed" translation. "indexada desde 1" or "con índice desde 1" - "indexada desde 1" works but maybe "basada en índice 1" is better. Actually "1-indexed" in Spanish programming context is often "indexado desde 1" or "con indexación desde 1". I'll use "indexada desde 1" which is clear.

Also, I should check if "asistentes" is right for "helpers". In Spanish, "helpers" in programming context is often translated as "ayudantes" but "asistentes" works too. Actually "funciones auxiliares" might be better. Let me think... "Connection lifecycle helpers" → "Funciones auxiliares del ciclo de vida de la conexión". That sounds more natural. Or "Asistentes del ciclo de vida de la conexión". I'll go with "Funciones auxiliares para el ciclo de vida de la conexión" - that's clearer.

Actually, let me keep it simple: "Ayudantes del ciclo de vida de la conexión" - hmm, "helpers" is often left as "helpers" in Spanish tech docs, but "asistentes" or "funciones auxiliares" works. I'll use "Funciones auxiliares del ciclo de vida de la conexión."

Let me also reconsider "Correo y búsqueda" - that works.

One more check: the em dash in "Download attachment..." - the original uses parentheses, not em dashes)Skip - I see the original just uses regular text.

I think my translation is solid. Let me finalize.# maildoc

Herramientas ligeras de búsqueda de correos electrónicos, recuperación de adjuntos y extracción de PDF para agentes de IA y automatización.

## Configuración

GXP1

Establece las credenciales en `.env` (consulta `.env.example`):

GXP2

## Inicio rápido

GXP3

## Servidor MCP (Claude Desktop / Cursor / Antigravity)

Ejecuta como servidor del Model Context Protocol (MCP):

GXP4

Ejemplo de `claude_desktop_config.json`:

GXP5

## Referencia de herramientas

### Correo y búsqueda

* `search_emails(sender, subject, body, seen, date_gte, date_lt, with_attachments, folder, limit)`: Busca en el buzón y devuelve diccionarios estructurados.
* `fetch_email_by_uid(uid, folder)`: Obtiene un único correo por UID.
* `list_folders()`: Lista las carpetas del buzón.
* `mark_email_as_read(uid, folder)`: Marca el correo como leído.
* `move_email(uid, destination_folder, source_folder)`: Mueve el correo entre carpetas.
* `delete_email(uid, folder)`: Elimina el correo.
* `create_folder(folder_name)`: Crea una carpeta en el buzón.
* `delete_folder(folder_name)`: Elimina una carpeta del buzón.
* `connect_to_email()`, `disconnect_from_email()`: Asistentes del ciclo de vida de la conexión.

### Extracción de PDF

* `read_pdf_attachment(uid, attachment_filename, password=None, folder="INBOX")`: Descarga el adjunto y extrae su texto directamente en un solo paso (ideal para MCP / agentes de IA).
* `extract_pdf_text(pdf_bytes, password=None)`: Extrae todo el texto de los bytes del PDF.
* `extract_pdf_page_text(pdf_bytes, page_number, password=None)`: Extrae el texto de una página específica (indexada desde 1).