mailoo

Mailoo

Mailoo（@bitfloo/mailoo）是由 Bitfloo 开发和维护的电子邮件（IMAP/SMTP）、日历、提醒事项及 ManageSieve 自动化 MCP 服务。

支持 AI 助手和自主 Agent 跨多个账户读取、搜索、发送、管理、安排和分析电子邮件、日历、提醒事项及 ManageSieve 筛选脚本。通过 MCP 2025/2026 协议提供多达 57 个工具（采用 full、core 和 minimal 工具集配置）、多达 7 个提示词和 6 个资源，并支持 outputSchema / structuredContent、OAuth2 (实验性)、电子邮件定时发送、日历提取、分析、提供商感知型标签管理、配备 AI 分类功能的实时 IMAP IDLE 监视器、可自定义的预设和静态规则、ManageSieve 筛选器，以及引导式设置向导。

关于已发送副本、IMAP4rev2、Sieve、附件 savePath、只读副作用及重连退避的行为说明，请参阅 docs/configuration.md 和 docs/tools.md。

亮点

目录

• 亮点
• 安全与沙箱架构
• 大模型易用性与工具集配置
• 文档
• 背景
• 安装
• 用法
• 功能与数据流
• API
• 维护者
• 参与贡献
• 致谢与许可证

安全与沙箱架构

政策及漏洞报告方式：SECURITY.md。

Mailoo 采用纵深防御沙箱机制，确保 AI Agent 能够安全地与不可信邮件和外部服务交互：

• 零 Shell 执行（仅使用 execFile） — 原生操作系统集成（用于 EventKit/Reminders/通知的 macOS osascript、Linux notify-send、Windows powershell，以及 crontab 安装）均通过严格的参数数组（shell: false）调用 child_process.execFile，从而消除命令注入途径。
• SSRF 与 DNS 重绑定防护（net.BlockList） — 出站告警 Webhook 会使用 IPv4/IPv6 net.BlockList 校验 URL。该列表涵盖环回地址、RFC 1918 私有地址范围、链路本地地址/云元数据地址（169.254.169.254、100.100.100.200）、CGNAT、NAT64、6to4 和保留前缀；校验会在配置时和套接字连接时（createWebhookConnectLookup）进行，以防止 DNS 重绑定攻击（src/safety/validation.ts）。
• 禁止符号链接的写入限制（savePath） — 通过 savePath 导出附件和 .eml 文件时，写入范围严格限制在工作目录内；系统会使用 lstat 遍历每个路径段，拒绝隐藏点文件和操作系统持久化目录（Library/LaunchAgents、.ssh、.gnupg），并在 50 MiB 文件大小上限（内联 base64 上限为 5 MiB）下使用 O_CREAT | O_EXCL | O_NOFOLLOW 打开目标文件。
• 提示词注入隔离（<<<UNTRUSTED_EXTERNAL_CONTENT>>>） — 不可信邮件主题、发件人标头、邮件正文、预览和身份验证结果都会用 <<<UNTRUSTED_EXTERNAL_CONTENT>>> … <<<END_UNTRUSTED_EXTERNAL_CONTENT>>> 分隔符包裹（并剥离载荷中伪造的标记），确保大模型将外部邮件视为数据，而非指令。
• 严格的凭据文件权限（0600） — config.toml 会在权限为 0700 的配置目录（$XDG_CONFIG_HOME/mailoo/config.toml）中以 0600 模式写入并验证。密码和邮件正文会从 JSONL 写入审计日志中删除（src/safety/audit.ts）。
• TLS 与 STARTTLS 验证 — tls 强制使用隐式 TLS 并验证证书（默认 verify_ssl = true）；如果服务器未声明支持 STARTTLS，starttls 会安全失败。只有环回主机才允许同时关闭两者。ManageSieve 不允许在未加密的套接字上使用 AUTHENTICATE PLAIN，除非已启用 STARTTLS。
• 运行防护措施（MCP_EMAIL_READ_ONLY、MCP_EMAIL_TOOLSET、dryRun） —
  • MCP_EMAIL_READ_ONLY=true 会在启动时禁用所有写入工具、后台监视器、钩子和调度器，仅开放 31 个只读工具。
  • MCP_EMAIL_TOOLSET=full|core|minimal 会根据 Agent 的能力级别和上下文预算，限制已注册的工具范围。
  • 对高风险工具（send_email、reply_email、forward_email、send_draft、delete_email、bulk_action、delete_mailbox、sieve_put_script、sieve_delete_script）设置 dryRun: true，会验证所有参数和账户解析，并返回 [DRY RUN] 预览，而不修改服务端状态。
• 按账户限流 — rate_limit（默认每分钟发送 10 次）会为每个账户独立执行令牌桶限流（src/safety/rate-limiter.ts）。令牌桶存储在内存中，因此每个服务进程和每次 mailoo scheduler check 运行都会分别计数。

大模型易用性与工具集配置

Mailoo 专为适配前沿模型（Claude、GPT、Gemini）以及本地/小型 3B–8B 参数模型（llama.cpp GBNF 语法、Ollama、vLLM）而设计：

• 工具集配置（MCP_EMAIL_TOOLSET / settings.toolset）：
  • full （默认） — 全部 57 个工具（在 read_only 模式下为 31 个），包括 Calendar、Reminders、ManageSieve、Watcher、Scheduler、Templates、Contacts 和 Analytics。
  • core — 19 个工具（在 read_only 模式下为 10 个），涵盖核心邮件工作流（accounts、mailboxes、emails、threads、send、drafts、manage、bulk、attachments、health）。
  • minimal — 14 个工具（在 read_only 模式下为 8 个），专为上下文预算有限的 3B–4B 模型定制（accounts、mailboxes、emails、send、manage、health）。
• 可选的 account 与智能账户解析 — 如果只配置了一个账户，或设置了 default_account（MCP_EMAIL_DEFAULT_ACCOUNT），则所有工具中的 account 参数都完全可选。账户查找还支持按配置名称或电子邮件地址进行大小写不敏感匹配（例如，传入 "[email protected]" 会解析到匹配的账户）；存在歧义时，会返回可执行的错误消息，列出有效账户（name (email) 对）。
• 无损参数规范化与 GBNF 兼容性 — 单邮件工具接受字符串或整数形式的 emailId、id 或 email_id（42 或 "42"）。批量工具（get_emails、bulk_action）接受字符串或数字 ID 数组（["42", "43"] 或 [42, 43]）。list_emails 和 search_emails 同时接受 hasAttachment 和 has_attachment。所有 Zod 模式都避免使用正则前瞻，因此 llama.cpp GBNF 语法编译可以顺利完成，不会报错。
• 上下文窗口保护 — get_email 和 get_thread 默认使用 format="text"，并将默认 maxLength 限制为 20000 个字符（超出时会附加明确的截断提示），避免大型 HTML 新闻邮件溢出小型上下文窗口。
• MCP 2025/2026 outputSchema 与 structuredContent — 工具声明结构化的 outputSchema 契约，并在返回可读文本块的同时提供机器可读的 structuredContent。
• 发出的附件路径必须指向工作目录或主目录下的常规文件 — 安全注意事项

文档

背景

大多数 MCP 邮件实现只提供基本的读取/发送功能。此服务旨在为 AI 助手提供功能全面的邮件客户端，涵盖邮件的整个生命周期：阅读、撰写、管理、安排和分析 — 全部通过单个 MCP 服务完成。

关键设计决策：

• 符合 XDG 规范的配置 — TOML 文件位于 ~/.config/mailoo/config.toml
• 多账户 — 同时操作多个 IMAP/SMTP 账户
• 分层服务 — 将业务逻辑与 MCP 接线解耦，以便进行测试
• 提供商自动检测 — Gmail、Outlook、Yahoo、iCloud、Fastmail、ProtonMail、Zoho、GMX

安装

需要 Node.js ≥ 24。

npx -y @bitfloo/mailoo account add

该命令会写入本地配置并打印 MCP 客户端代码片段。同一软件包也可用于运行服务和其他命令：

npx -y @bitfloo/mailoo
npx -y @bitfloo/mailoo test

不带子命令运行 npx -y @bitfloo/mailoo，会通过 stdio 启动 MCP 服务。也可以安装 mailoo 命令：

npm install -g @bitfloo/mailoo
# or
pnpm add -g @bitfloo/mailoo
# or, without a global install:
pnpm dlx @bitfloo/mailoo account add

从克隆版本安装

构建此仓库需要 pnpm 12（即 package.json 中 packageManager 指定的版本）：

git clone https://github.com/Bitfloo/mailoo.git
cd mailoo
pnpm install && pnpm build
node dist/main.js account add

Docker

运行镜像需要 Docker，无需在主机上安装 Node。先使用 npx -y @bitfloo/mailoo account add 创建配置（或手动编写 TOML），然后将该目录挂载到容器中。

镜像为 ghcr.io/bitfloo/mailoo，适用于 linux/amd64 和 linux/arm64。标签采用纯 semver 格式（不带 v 前缀）。0.3 标签会跟随最新的 0.3.x 版本。生产环境应固定到发行版本的完整版本号（与 npm 版本一致）或镜像摘要。

docker pull ghcr.io/bitfloo/mailoo:0.3

若要从克隆的仓库构建（docker-compose.yml 使用 build: .）：

docker build -t ghcr.io/bitfloo/mailoo .

注意： 服务使用 stdio 传输。配置在主机上创建（使用 npx -y @bitfloo/mailoo account add，或手动编写 TOML），然后挂载到容器中。

用法

以下命令使用 npx -y @bitfloo/mailoo。全局安装也接受与 mailoo 相同的子命令。从克隆的仓库运行时，执行 pnpm build 后，这些子命令为 node dist/main.js（参见从克隆的仓库运行）。

设置

# Add an email account interactively (recommended)
npx -y @bitfloo/mailoo account add

# Or use the deprecated alias (same wizard)
npx -y @bitfloo/mailoo setup

# Or create a template config manually
npx -y @bitfloo/mailoo config init

设置向导会自动检测服务设置、测试连接、保存配置，并输出 MCP 客户端配置代码片段。

测试连接

npx -y @bitfloo/mailoo test            # all accounts
npx -y @bitfloo/mailoo test personal   # specific account

npx -y @bitfloo/mailoo test / mailoo test 是实时账户连接探测，不是 Vitest。单元测试和集成测试命令为 pnpm test / pnpm test:integration（参见贡献指南）。OAuth2 账户会使用配置的刷新令牌获取新的访问令牌并登录。

配置 MCP 客户端

运行引导式安装程序，或粘贴下方的代码片段。目前没有 VS Code / MCP gallery 条目。

npx -y @bitfloo/mailoo install

安装程序可以注册 npx、pnpm dlx 或全局 mailoo 启动方式。若 PATH 中已有 mailoo 二进制文件，可以使用 "command": "mailoo" 和 "args": ["stdio"]。

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo", "stdio"]
    }
  }
}

{
  "servers": {
    "mailoo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo", "stdio"]
    }
  }
}

{
  "mcp": {
    "servers": {
      "mailoo": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@bitfloo/mailoo", "stdio"]
      }
    }
  }
}

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo", "stdio"]
    }
  }
}

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo", "stdio"]
    }
  }
}

{
  "context_servers": {
    "mailoo": {
      "command": {
        "path": "npx",
        "args": ["-y", "@bitfloo/mailoo", "stdio"]
      }
    }
  }
}

[[mcp_servers]]
name = "mailoo"
transport = "stdio"
command = "npx"
args = ["-y", "@bitfloo/mailoo", "stdio"]

[[mcp_servers]]
name = "mailoo"
transport = "stdio"
command = "npx"
args = ["-y", "@bitfloo/mailoo", "stdio"]
env = { MCP_EMAIL_ADDRESS = "[email protected]", MCP_EMAIL_PASSWORD = "your-app-password", MCP_EMAIL_IMAP_HOST = "imap.example.com", MCP_EMAIL_SMTP_HOST = "smtp.example.com" }

docker run --rm -i \
  -v ~/.config/mailoo:/home/node/.config/mailoo:ro \
  ghcr.io/bitfloo/mailoo:0.3

{
  "mcpServers": {
    "mailoo": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "~/.config/mailoo:/home/node/.config/mailoo:ro",
        "ghcr.io/bitfloo/mailoo:0.3"
      ]
    }
  }
}

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo", "stdio"],
      "env": {
        "MCP_EMAIL_ADDRESS": "[email protected]",
        "MCP_EMAIL_PASSWORD": "your-app-password",
        "MCP_EMAIL_IMAP_HOST": "imap.example.com",
        "MCP_EMAIL_SMTP_HOST": "smtp.example.com"
      }
    }
  }
}

CLI 命令

npx -y @bitfloo/mailoo [command]

Commands:
  stdio                     Run as MCP server over stdio (default)
  http [port] [host]        Streamable HTTP (default: port 8080 on 127.0.0.1 and ::1)
  account list              List all configured accounts
  account add               Add a new email account interactively
  account edit [name]       Edit an existing account
  account delete [name]     Remove an account
  setup                     Deprecated alias for 'account add'
  test                      Test connections for all or a specific account
  install                   Register mailoo with MCP clients interactively
  install status            Show registration status for detected clients
  install remove            Unregister mailoo from MCP clients
  config show               Show config (passwords masked)
  config edit               Edit global settings (rate limit, read-only)
  config path               Print config file path
  config init               Create template config
  scheduler check           Process pending scheduled emails
  scheduler list            Show all scheduled emails
  scheduler install         Install OS-level scheduler (launchd/crontab)
  scheduler uninstall       Remove OS-level scheduler
  scheduler status          Show scheduler installation status
  notify test               Send a test desktop notification
  notify status             Check platform notification support
  --version, -v             Print the package version
  help                      Show help

HTTP

http 监听 127.0.0.1 和 ::1（除非指定其他端口，否则使用端口 8080）。非环回地址或 MCP_EMAIL_HTTP_ALLOWED_HOSTS 中的非环回名称需要设置 MCP_EMAIL_HTTP_TOKEN。详情（包括 0.0.0.0 / :: 和 8 MiB 的请求体限制）：docs/configuration.md。

npx -y @bitfloo/mailoo http
MCP_EMAIL_HTTP_TOKEN='replace-with-a-long-random-secret' npx -y @bitfloo/mailoo http 8080 192.0.2.10

配置了令牌时，客户端需发送 Authorization: Bearer <token>。

配置

位于 $XDG_CONFIG_HOME/mailoo/config.toml（默认：~/.config/mailoo/config.toml）。

[settings]
rate_limit = 10  # max emails per minute per account
read_only = false
toolset = "full"  # "full" | "core" | "minimal"
default_account = "personal"  # optional when only one account is configured
save_to_sent = true  # see docs/configuration.md — Gmail already files Sent

[[accounts]]
name = "personal"
email = "[email protected]"
full_name = "Your Name"
password = "your-app-password"

[accounts.imap]
host = "imap.example.com"
port = 993
tls = true
# disable_imap4rev2 = true  # Strato and similar SEARCH bugs
# sieve_host = "imap.example.com"
# sieve_port = 4190

[accounts.smtp]
host = "smtp.example.com"
port = 465
tls = true
starttls = false
verify_ssl = true

[accounts.smtp.pool]
enabled = true
max_connections = 1
max_messages = 100

如果文件中或通过 MCP_EMAIL_* 设置的 IMAP 或 SMTP 块包含 tls = false 和 starttls = false，则只有当主机为 localhost、以完整形式书写的 127.0.0.0/8 地址（例如 127.0.0.1）或 ::1 时才会加载；其他任何主机都会在配置加载时被拒绝。

OAuth2 （实验性）

注意： OAuth2 支持为实验性功能。令牌刷新和特定于提供商的流程可能需要在您的环境中进行额外测试。

令牌刷新和代码交换会在 15 秒后放弃，因此停止响应的提供商会导致连接失败，并返回 OAuth2 token refresh timed out after 15s，而不是一直挂起。同时需要新令牌的调用方会共用一个刷新请求。IDLE 监视器使用相同的访问令牌登录。

[[accounts]]
name = "work"
email = "[email protected]"
full_name = "Your Name"

[accounts.oauth2]
provider = "google"            # or "microsoft"
client_id = "your-client-id"
client_secret = "your-client-secret"
refresh_token = "your-refresh-token"

[accounts.imap]
host = "imap.example.com"
port = 993
tls = true

[accounts.smtp]
host = "smtp.example.com"
port = 465
tls = true

[accounts.smtp.pool]
enabled = true
max_connections = 1
max_messages = 100

环境变量

适用于单账户配置（覆盖配置文件）：

如果未设置电子邮件地址、两个主机以及密码或提供商，环境变量就未描述任何账户：Mailoo 会加载配置文件；如果配置文件不存在，则会报错 No configuration found.。

已发送邮件副本、IMAP4rev2、Sieve 主机/端口和 read_only 环境变量： docs/configuration.md。

邮件计划发送

该计划程序采用分层架构，可在未来发送邮件：

1. MCP 自动检查 — 在服务启动时、监视器连接之前，以及 MCP 服务运行期间每隔 60 秒处理队列。运行多个 stdio 服务时，只有运行监视器和钩子的服务会执行检查。如果上一次检查在下一次检查到期时仍在运行，则跳过下一次检查；发送失败时，会以 warning 级别记录到已连接的 MCP 客户端
2. 命令行 — 使用 npx -y @bitfloo/mailoo scheduler check 手动处理或基于 cron 处理。它使用与服务相同的账户设置进行发送，包括 OAuth2 和 save_to_sent，并会在退出前关闭 IMAP/SMTP 连接
3. 操作系统级守护进程 — npx -y @bitfloo/mailoo scheduler install 会设置 launchd（macOS）或 crontab（Linux），每分钟运行一次，独立于 MCP 服务

重要 — 必须安装守护进程，才能可靠地发送邮件。 如果未安装，只有在 AI 客户端处于活动连接状态时，计划邮件才会发送。 计划发送时，计算机也必须处于运行状态；如果计算机处于睡眠或关机状态， 守护进程会在下次唤醒/启动时处理逾期邮件。发送失败时， 最多会重试 3 次，之后邮件会被标记为 failed。

设置守护进程

# Install (macOS launchd / Linux crontab — runs every minute)
npx -y @bitfloo/mailoo scheduler install

# Verify it's running
npx -y @bitfloo/mailoo scheduler status

# View pending / sent / failed scheduled emails
npx -y @bitfloo/mailoo scheduler list

# Trigger a manual check immediately
npx -y @bitfloo/mailoo scheduler check

# Remove the daemon
npx -y @bitfloo/mailoo scheduler uninstall

计划邮件以 JSON 文件的形式存储在 ~/.local/state/mailoo/scheduled/ 中。发送前，检查会使用条目旁的锁文件认领该条目，并在 SMTP 运行期间持续更新认领状态，因此进程内计时器、mailoo scheduler check 和其他服务进程不会重复发送。如果进程在服务接受邮件后、将其记录为已发送之前退出，那么认领状态过期后，该条目可能会再次发送（至少一次，而非恰好一次）。同一条目的每次尝试都会使用相同的 Message-ID：<schedule id@account domain>，因此接收服务器或客户端可以丢弃重复邮件。SMTP 接受邮件后，如果更新队列文件失败，系统会报告该故障；只要已发送记录写入成功，或文件已移至 sent/，就不会再次发送该条目。如果两者都失败，下一次检查会再次发送，除非该条目已用完所有尝试次数；用完后，该条目会被标记为 failed。每个条目都会跟踪尝试次数（最多 3 次）和上次错误；list_scheduled 会返回两者，scheduler list 会显示失败条目的错误。被速率限制暂缓处理的条目会保持待处理状态，留待下次检查，不会消耗尝试次数。

实时监视器与 AI 钩子

IMAP IDLE 监视器通过持久 IDLE 连接实时监控已配置的邮箱（与工具连接分开）。每个文件夹在获取邮件之间都会保持 IDLE；每次获取后，IDLE 会在约一秒后恢复；idle_timeout 用于设置 IDLE 重启频率。同一台计算机上运行多个 stdio 服务（每个 MCP 客户端窗口一个）时，只有其中一个会运行监视器、钩子和计划程序；请参阅配置。收到新邮件时：

1. 静态规则 — 按发件人/收件人/主题进行模式匹配 → 立即应用标签、加旗标或标记为已读（不使用 AI）
2. AI 分类 — 通过 MCP 采样，使用可自定义的预设提示词分析剩余邮件
3. 通知模式 — 如果禁用 AI 分类，则改为记录日志

在 config.toml 中配置：

[settings.watcher]
enabled = true
folders = ["INBOX"]
idle_timeout = 1740     # 29 minutes (IMAP spec max is 30)

[settings.hooks]
on_new_email = "triage" # "triage" | "notify" | "none"
preset = "inbox-zero"   # "inbox-zero" | "gtd" | "priority-focus" | "notification-only" | "custom"
auto_label = true       # apply AI-suggested labels
auto_flag = true        # flag urgent emails
batch_delay = 5         # seconds to batch before triage

# User context — appended to preset's AI prompt
custom_instructions = """
I'm a software engineer. Emails from @example.com are always high priority.
Newsletters I read: TL;DR, Hacker Newsletter.
"""

# Static rules — run BEFORE AI, skip AI if matched
[[settings.hooks.rules]]
name = "GitHub Notifications"
match = { from = "*@example.com" }
actions = { labels = ["Dev"], mark_read = true }

[[settings.hooks.rules]]
name = "Newsletter Archive"
match = { from = "*@example.com|*@example.test" }
actions = { labels = ["Newsletter"] }

[[settings.hooks.rules]]
name = "VIP Contacts"
match = { from = "[email protected]|[email protected]" }
actions = { flag = true, labels = ["VIP"] }

每次只运行一个批次。最多 500 封新邮件会等待下一个批次；超出的邮件会被跳过，并在日志中发出警告，同时保持在邮箱中不变。

预设

静态规则

静态规则使用 glob 风格的模式（*@example.com），并以 | 作为 OR 分隔符（*@example.com|*@example.test）。匹配项中的所有条件均采用 AND 逻辑。to 模式在任一收件人匹配时即视为匹配。空模式视为无条件，而没有任何条件的规则不会匹配任何内容。以第一个匹配的规则为准。

可用操作：labels（字符串数组）、flag（布尔值）、mark_read（布尔值）、alert（布尔值 — 强制发送桌面通知）。

警报

基于紧急程度的多渠道通知路由 — 即使你没有查看聊天，也能让重要邮件吸引你的注意。所有渠道均需主动启用，且默认禁用。

指定级别的 MCP 日志条目会记录账户、文件夹、UID、标签和规则。在警报条目中，发件人和主题仅会出现在 debug 级别：单独记录一条，或在 low 级别下记录在唯一一条日志中。

[settings.hooks.alerts]
desktop = true              # OS-level notifications (macOS/Linux/Windows)
sound = true                # play sound for urgent emails
urgency_threshold = "high"  # minimum priority to trigger desktop alert
webhook_url = "https://ntfy.sh/my-email-alerts"  # optional: Slack, Discord, ntfy.sh, etc.
webhook_events = ["urgent", "high"]
allow_private_webhooks = false  # default; true allows a LAN, VPN, or tailnet target

详情：docs/configuration.md。

支持的平台： macOS（通过 osascript 使用通知中心）、Linux（notify-send）、Windows（PowerShell toast 通知）。不依赖任何 npm 包 — 使用操作系统原生命令。

各平台的通知设置：

# Ubuntu / Debian
sudo apt install libnotify-bin pulseaudio-utils

# Fedora
sudo dnf install libnotify pulseaudio-utils

# Arch
sudo pacman -S libnotify

可由 AI 配置： AI 可以在运行时检查、测试和配置通知：

• check_notification_setup — 诊断平台支持情况并显示设置说明
• test_notification — 发送测试通知以验证一切正常
• configure_alerts — 启用/禁用桌面通知、声音、阈值和 webhook（可选择持久保存到配置文件）

Webhook 负载：

{
  "event": "email.urgent",
  "account": "work",
  "sender": { "name": "John CEO", "address": "[email protected]" },
  "subject": "Q4 Review Due Today",
  "priority": "urgent",
  "labels": ["VIP"],
  "rule": "VIP Contacts",
  "timestamp": "2026-02-18T11:30:00Z"
}

无论紧急程度阈值如何，静态规则都可以通过 alert = true 强制发送桌面通知：

[[settings.hooks.rules]]
name = "VIP Contacts"
match = { from = "[email protected]" }
actions = { flag = true, alert = true, labels = ["VIP"] }

功能：

• 自动重连 — 按照重连退避计划重试已断开或失败的文件夹连接；连接中断期间送达的邮件会在重连后报告，除非服务器更改了该文件夹的 UIDVALIDITY；尚未连接过的文件夹只会报告首次成功连接后收到的邮件
• 批处理 — 将可配置延迟时间内收到的邮件合并，以减少 AI 调用
• 速率限制 — 每分钟最多 10 次采样调用
• 优雅降级 — 如果客户端不支持采样，则回退到通知模式

System One（选择启用的类型化归档）

对静态规则处理后剩余的邮件，可选择启用 TypeSafe System One 分类。默认关闭。 必须同时启用 settings.watcher.enabled 和 settings.system_one.enabled。在环境中设置 TYPESAFE_API_KEY（切勿写入 TOML）。

仅对 source_folders 中（默认为 INBOX）且未被任何静态规则处理的新邮件进行分类。对于每封此类邮件，Mailoo 会向 api.typesafe.ai（或 TYPESAFE_BASE_URL）发送一次请求。请求包含以下内容（src/services/mail-arrival/state.ts、src/services/mail-arrival/questions.ts）：

不会发送：To、Cc 和 Bcc 地址、Message-ID、其他原始标头、附件内容，以及 include_body 为 false 时的正文。

Mailoo 会记住最近分类的 5000 封邮件，不会再次发送。同一封邮件到达你的两个账户时，会在每个账户中各分类一次。若邮件请求失败或标头读取失败，则不会记住该邮件，因此下次收到通知时会重试。

auto_move 和 auto_flag 是独立开关，默认均为 false。归档目标取自 folders[].path（通过 IMAP LIST 验证），而不是实时列出所有邮箱。

[settings.system_one]
enabled = false
include_body = false
auto_move = false
auto_flag = false

[[settings.system_one.folders]]
path = "Receipts"
description = "Invoices, receipts, and payment confirmations."

启用 System One 后，on_new_email = "notify" 和 "triage" 都会将邮件交给它处理。none 则保持关闭。

功能与数据流

下文列出 src/ 中会执行的出站调用、子进程、文件操作和环境变量。使用 MCP sampling 的钩子分流流程会留在已连接的客户端内；对于该流程，Mailoo 不会另行连接模型主机。

网络

mailoo http 负责监听，不会新增出站目标。src/cli/providers.ts 中的提供商预设会填入向导保存的 IMAP 和 SMTP 主机。

进程

文件

除非设置了 XDG_CONFIG_HOME、XDG_DATA_HOME 或 XDG_STATE_HOME，否则路径遵循 src/config/xdg.ts 中的 XDG 默认值。

服务只会读取 $XDG_CONFIG_HOME/mailoo/templates/ 下的模板，不会写入这些模板。

环境

单账户配置读取 MCP_EMAIL_*（src/config/loader.ts）。HTTP 监听配置读取 MCP_EMAIL_HTTP_HOST、MCP_EMAIL_HTTP_TOKEN 和 MCP_EMAIL_HTTP_ALLOWED_HOSTS（src/safety/http-transport.ts）。同名配置项也是 Smithery 配置键，以及 server.json 中的 packages[].environmentVariables 列表。

API

工具（57）

读取（19）

写入（12）

管理（7）

标签（5）

注意： 在将标签存储为 IMAP 关键字的服务器上，关键字必须是 IMAP 原子（RFC 9051）：不得包含空格、控制字符或非 ASCII 字符，也不得包含 ( ) { % * " \ ] 中的字符。 任何其他标签都会在发送任何内容之前被拒绝并返回错误，因此 Receipts (2024) 会失败（旧版本曾接受该标签）。有关移除现有非原子关键字的信息，请参阅 add_label / remove_label。

监视器与提醒（6）

日历与提醒事项（8）

以上工具的参数说明：docs/tools.md。

提示词（7）

仅当工具集注册了提示词所调用的工具时，才会列出该提示词：summarize_thread 需要 core 或 full，summarize_meetings 需要 full。如果缺少发送、草稿或批量处理工具（minimal、read_only），提示词会跳过相应步骤。

资源（6）

提供商自动检测

架构

src/
├── main.ts                — Entry point and subcommand routing
├── server.ts              — MCP server factory
├── logging.ts             — MCP protocol logging bridge
├── cli/                   — Interactive CLI commands
│   ├── account-commands.ts — Account CRUD (list, add, edit, delete)
│   ├── setup.ts           — Legacy setup alias → account add
│   ├── test.ts            — Connection tester
│   ├── config-commands.ts — Config management (show, edit, path, init)
│   ├── install-commands.ts — MCP client registration (install, status, remove)
│   ├── providers.ts       — Provider auto-detection (IMAP/SMTP presets)
│   └── scheduler.ts       — Scheduler CLI
├── config/                — Configuration layer
│   ├── xdg.ts             — XDG Base Directory paths
│   ├── schema.ts          — Zod validation schemas
│   └── loader.ts          — Config loader (TOML + env vars)
├── connections/
│   ├── auth.ts            — IMAP/SMTP credentials (password or OAuth2)
│   ├── backoff.ts         — Reconnect delays with jitter after a failed connect
│   ├── manager.ts         — Lazy persistent IMAP/SMTP with OAuth2 (experimental)
│   └── probe.ts           — One-shot IMAP/SMTP login checks (setup wizard, mailoo test)
├── services/              — Business logic
│   ├── imap.service.ts    — IMAP operations
│   ├── label-strategy.ts  — Provider-aware label strategy (ProtonMail/Gmail/IMAP keywords)
│   ├── smtp.service.ts    — SMTP operations + optional \\Sent APPEND
│   ├── sieve.service.ts   — ManageSieve (RFC 5804)
│   ├── template.service.ts — Email template engine
│   ├── oauth.service.ts   — OAuth2 token management (experimental)
│   ├── mail-services.ts   — IMAP/SMTP services from the config, for the servers and the scheduler CLI
│   ├── calendar.service.ts — ICS/iCalendar parsing
│   ├── scheduler.service.ts — Email scheduling queue
│   ├── watcher.service.ts — IMAP IDLE real-time watcher with auto-reconnect
│   ├── hooks.service.ts   — AI triage via MCP sampling + static rules + auto-labeling/flagging
│   ├── notifier.service.ts — Multi-channel notification dispatcher (desktop/sound/webhook)
│   ├── presets.ts         — Built-in hook presets (inbox-zero, gtd, priority-focus, etc.)
│   └── event-bus.ts       — Typed EventEmitter for internal email events
├── tools/                 — MCP tool definitions (57)
├── prompts/               — MCP prompt definitions (7)
├── resources/             — MCP resource definitions (6)
├── safety/                — Audit trail, rate limiter, stdio lifecycle, shutdown, writer lease
│   └── http-transport.ts  — Streamable HTTP listen policy
├── utils/                 — RFC 2047 compose, MIME body, auth headers
└── types/                 — Shared TypeScript types

维护者

Bitfloo

参与贡献

接受针对 develop（GitHub 默认分支）的 PR。develop 是发布分支；发布版本会基于该分支打上 v* 标签。编辑此 README 时，请遵循 standard-readme 规范。请参阅 CONTRIBUTING.md。

# Development workflow
pnpm install
pnpm typecheck          # type check
pnpm check              # lint and format
pnpm ci:local           # lint, typecheck, unit; GreenMail if Docker is up
pnpm test               # unit tests (Vitest; no mail server)
pnpm test:integration   # GreenMail IMAP/SMTP (needs Docker)
pnpm test:all           # unit plus GreenMail
pnpm build              # build
pnpm start              # run

pnpm test:integration 和 pnpm test:all 需要 Docker。Docker 未运行时，pnpm ci:local 会跳过 GreenMail。GitHub 在拉取请求中运行的内容列于 CONTRIBUTING.md。mailoo test / npx -y @bitfloo/mailoo test 用于探测真实账户连接，并非 Vitest。

归属与许可

这是由 codefuturist 开发的 email-mcp 的公开 LGPL-3.0-or-later 分支。它并非 codefuturist 的官方项目。原始版权仍归原作者所有。 Mailoo 品牌、Bitfloo 商标和新增代码的版权归 Bitfloo 所有，版权年份为 2026 年。

依据 LGPL-3.0-or-later 授权。LGPL-3 要求的 GNU GPL-3 文本位于 COPYING。 归属信息记录于 NOTICE。