轻量级电子邮件搜索、附件检索和 PDF 提取工具，适用于 AI 智能体和自动化。
pip install -r requirements.txt在 .env 中设置凭据（参见 .env.example）：
GMAIL_USERNAME=user@example.com
GMAIL_APP_PASSWORD=your_app_passwordRelated MCP server: Gmail MCP Server
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)作为 Model Context Protocol (MCP) 服务器运行：
python server.py示例 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"
}
}
}
}search_emails(sender, subject, body, seen, date_gte, date_lt, with_attachments, folder, limit)：搜索邮箱并返回结构化字典。
fetch_email_by_uid(uid, folder)：按 UID 获取单个电子邮件。
list_folders()：列出邮箱文件夹。
mark_email_as_read(uid, folder)：将电子邮件标记为已读。
move_email(uid, destination_folder, source_folder)：在文件夹之间移动电子邮件。
delete_email(uid, folder)：删除电子邮件。
create_folder(folder_name)：创建邮箱文件夹。
delete_folder(folder_name)：删除邮箱文件夹。
connect_to_email()、disconnect_from_email()：连接生命周期辅助函数。
read_pdf_attachment(uid, attachment_filename, password=None, folder="INBOX")：下载附件并直接一步提取其文本（非常适合 MCP / AI 智能体）。
extract_pdf_text(pdf_bytes, password=None)：从 PDF 字节中提取全部文本。
extract_pdf_page_text(pdf_bytes, page_number, password=None)：从特定页面（从 1 开始索引）提取文本。
This server cannot be deployed
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Gmail, Outlook, iCloud, Fastmail and any IMAP mailbox for your agent. Scoped OAuth, no send tool.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
