Skip to main content
Glama
MailBridge_mcp

MailBridge_mcp

统一邮件与附件读取工具

独立运行的 Python 工具,提供命令行与本地 stdio MCP 接口。支持多账号绑定、分页列收件箱、读取正文、下载附件和整封邮件导出。

验证状态

邮箱

适配器实现

模拟测试

真实邮箱验证

Outlook 个人邮箱

已完成

已通过

已通过:正文、附件和文件一致性

Gmail

已完成

已通过

未完成:缺少 Google OAuth 客户端配置及用户授权

QQ

已完成

已通过

未完成:缺少用户 IMAP 授权

其他 IMAP

通用适配已实现

已通过

未逐厂商验证

模拟测试不代表真实服务接入已验证。当前是本机单用户工具,不是公开部署的多租户服务。

Related MCP server: mcp-email-server

快速开始

uv sync --locked
uv run python -m mail_tool accounts
uv run python -m mail_tool list --account outlook-main --limit 5
uv run python -m mail_tool get --account outlook-main --message '邮件ID'
uv run python -m mail_tool export --account outlook-main --message '邮件ID'

本机已有账号 outlook-main 可直接使用。新邮箱先绑定:

uv run python -m mail_tool bind outlook --account outlook-main --client-id '微软应用ClientID'
uv run python -m mail_tool bind gmail --account gmail-main --credentials .state/google-client.json
uv run python -m mail_tool bind qq --account qq-main --email '你的邮箱@qq.com'

Gmail 使用 Desktop OAuth JSON 和浏览器授权;QQ 在终端隐藏输入客户端授权码。不要将凭据写入聊天或提交到 Git。

config.example.json 仍可复制为 config.json 保存 Microsoft Client ID。原授权缓存和历史下载文件保留,旧代码已迁入 mail_tool;不再使用旧模块入口。

MCP 和测试

uv run python -m mail_tool serve
uv run python -m unittest discover -v

MCP 提供 mail_list_accounts、mail_list_messages、mail_get_message、mail_download_attachment、mail_export_message。

完整绑定步骤、MCP客户端配置、Provider扩展方法和当前边界见 邮件工具使用说明。

代码结构

  • mail_tool/outlook_auth.py:微软授权与令牌缓存。

  • mail_tool/providers.py:Provider协议和三类邮箱适配器。

  • mail_tool/common.py:MIME解析、文件名处理、游标及文件保存。

  • mail_tool/service.py:统一账号、邮件和附件服务。

  • mail_tool/main.py:命令行入口。

  • mail_tool/mcp_server.py:MCP接口。

下一步分别绑定 Gmail、QQ,用含正文和附件的测试邮件执行 list → get → export,核对正文和原附件哈希。验证前不将两家标记为已接通。

Available Tools

5 tools
mail_download_attachmentA

下载原始附件到服务所在机器的受控目录,返回路径、大小、SHA256。不解析PDF/Word、不执行附件。

Inputs: account_id (required), message_id (required), attachment_id (required).

mail_export_messageA

将完整正文、元数据及非内嵌附件保存到本机;逐附件返回失败,complete 表示是否完整。

Inputs: account_id (required), message_id (required), include_attachments.

mail_get_messageA

获取邮件文本/HTML正文及附件ID。超长正文带 truncated 标记;需要完整落盘可调用 export。

Inputs: account_id (required), message_id (required), max_body_chars.

mail_list_accountsA

列出本地已配置邮箱及 account_id;configured 不代表授权实时有效。

Inputs: no named parameters.

mail_list_messagesA

分页列出指定邮箱收件箱邮件摘要;limit 1-50,使用返回的 next_cursor 继续。无全文搜索。

Inputs: account_id (required), limit, cursor.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct operation: list accounts, list messages, read one message, download one attachment, or persist a full message. get_message and export_message are related but clearly separated by in-memory reading vs disk export.

    Naming Consistency5/5

    All tool names use the consistent mail_<verb>_<noun> snake_case pattern with clear verbs: list, get, download, export. The convention is uniform and predictable.

    Tool Count5/5

    Five tools form a compact, focused set for an email bridging/export server. Each tool addresses a necessary step in the retrieval workflow without redundancy.

    Completeness4/5

    The read/export lifecycle is well covered: accounts, message listing, body retrieval, attachment download, and full export. Send, search, folder navigation, and authentication refresh are absent, but those appear out of scope for this bridge; their absence is a minor gap if broader email management is expected.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables email management for a single mailbox via IMAP and SMTP protocols. Supports reading, searching, and sending emails with threading support through stdio or HTTP transports.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables reading and sending emails via IMAP and SMTP through the MCP protocol. Supports multiple email accounts and configuration via UI or environment variables.
      BSD 3-Clause
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables searching, reading full conversations, and sending email across multiple IMAP/SMTP mailboxes from any MCP client, with multi-user support and per-user API tokens.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables read-only IMAP email access through MCP, including listing accounts and folders, searching messages, retrieving message bodies and attachments, and viewing threads without modifying mail state.
      MIT