Skip to main content
Glama
maildoc

maildoc

by Mohking1

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

Related MCP server: Gmail MCP Server

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

  • 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).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Full Gmail control for any MCP-compatible AI agent. Exposes ~40 tools for reading, composing, labeling, filtering, threading, and account management.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Production-ready MCP server for Gmail, enabling AI agents to search, read, send, draft, and manage emails, labels, and attachments via the Google Gmail API.
      -