Mail Shadow MCP

AI Agent 的私密、安全、智能收件箱

别再让 AI 直接访问你的电子邮件。为它提供安全、极速且功能丰富的“影子”副本。

---

使用 mail-shadow-mcp 可以做什么？

想象一下，有一位私人助手读过你的所有邮件，清楚哪些内容重要，并能在几秒内回答你的问题，同时避免因 AI 行为异常或产生幻觉而让你的真实邮箱面临风险。

使用 mail-shadow-mcp，你可以向 AI（例如 OpenClaw、Hermes Agent、Claude、Cursor 或任何其他自定义 Agent）提出问题：

• “过去 3 天里，我收到过 Amazon 发来的发票吗？”
• “总结一下老板最近关于项目状态的邮件往来。”
• “请总结‘Project’文件夹中所有未读邮件。”
• “检查我的收件箱中是否有下周的航班确认邮件。”
• “找出所有来自 ‘[email protected]’ 且带有附件的邮件。”
• “我的收件箱里有没有看起来像垃圾邮件的内容？”

---

为什么要开发它？

大多数 AI Agent 都需要直接访问你的电子邮件（IMAP）才能“查看”邮件。这存在风险——一旦 Agent 获得有效的 IMAP 凭据，它就拥有与你相同的权限：可以读取、移动、删除，甚至发送邮件。一次幻觉、一条被误解的指令或一个错误，都可能导致 AI 意外删除你的整个收件箱、发送你无意发送的回复，或将你的凭据泄露给第三方。

mail-shadow-mcp 通过创建一个“安全区”解决了这个问题：

1. **影子副本：**我们不会连接到你的真实邮件服务器，而是创建一个存储邮件的本地高速“影子”数据库（SQLite）。这还能解锁原始 IMAP 无法提供的功能：即时全文搜索所有文件夹和帐户、按已读／已回复状态、附件、日期范围和发件人进行复杂筛选——全程无需与邮件服务器往返通信。它也能轻松同时处理多个邮箱，只需在配置中添加更多帐户即可。
2. **完全隐私：**你的 AI Agent 只会与这个本地数据库交互。IMAP 凭据仅供同步引擎使用；任何 MCP 工具调用都不会暴露这些凭据，任何响应也不会将其返回给 Agent。
3. **“安全网”（软删除）：**即使你让 AI“删除”一封邮件，它也不会真的删除邮件，而只会将其移至你指定的“废纸篓”文件夹。如果出了问题，你可以随时检查该文件夹、恢复单封邮件，或自行永久删除邮件——控制权始终在你手中。

[Remote IMAP Server] ──IMAP──▶ [Sync Engine] ──▶ [SQLite FTS5] ◀──▶ [MCP Server] ◀──▶ [AI Agent]

---

开始使用

推荐通过 Docker 运行 mail-shadow-mcp。在容器中运行可将同步引擎、凭据和数据库与通过 HTTP 连接的 AI Agent 完全隔离。Agent 无法访问主机文件系统或你的 IMAP 密码，只能访问 MCP API。

如果你想不使用 Docker 在本地运行，可以从发布页面下载预编译二进制文件，并改用 stdio 传输方式。不过，这意味着 Agent 进程与 mail-shadow-mcp 共享同一个用户上下文，会降低上述隔离效果。

步骤 1 — 启动容器以生成示例配置

创建本地配置和数据目录，然后首次运行以生成示例配置：

mkdir -p ./config ./data

docker run --rm \
  -v ./config:/config \
  -v ./data:/data \
  ghcr.io/dryas/mail-shadow-mcp:latest

容器会检测到不存在 config.yaml，将带注释的示例配置复制到 ./config/，打印一条消息，然后退出。

步骤 2 — 编辑配置文件

打开 ./config/config.yaml（或挂载 /config 卷的位置），填写 IMAP 详细信息：

sync_interval_min: 15

database:
  path: "/data/mail.db"

attachment_dir: "/data/attachments"

transport: http
http_addr: ":8080"
http_bearer_token: "your-secret-token"   # generate one: openssl rand -hex 32

accounts:
  - id: "[email protected]"
    host: "imap.example.com"
    port: 993
    username: "[email protected]"
    password: "$WORK_IMAP_PASS"          # resolved from environment variable at startup
    tls_mode: tls                        # tls (default) | starttls | none
    tls_skip_verify: false               # set true for self-signed certificates
    folders: ["INBOX", "Archive"]        # omit to sync all folders
    idle_folders: ["INBOX"]              # optional: instant new-mail push via IMAP IDLE
    trash_folder: "llm_delete"           # target folder for soft-deletes via delete_mail

将密码设为环境变量： 不要将 IMAP 密码直接写入配置文件，而是使用 $VARIABLE_NAME 占位符——mail-shadow-mcp 会在启动时从容器的环境变量中读取密码。上面的示例中，password: "$WORK_IMAP_PASS" 表示容器会从 WORK_IMAP_PASS 环境变量中读取值；启动容器时，通过 -e WORK_IMAP_PASS=your_password_here 传入该变量（参见步骤 1 或 3）。这样，配置文件中就不会出现明文密码。

folders： 要同步的 IMAP 文件夹列表。如果省略，则同步所有文件夹。仅同步你实际需要的文件夹（例如 ["INBOX", "Archive"]），可以减小数据库体积并加快首次同步。

idle_folders： 可选的文件夹列表，mail-shadow-mcp 会为这些文件夹打开持久的 IMAP IDLE 连接。当邮件服务推送 "EXISTS" 通知时，会立即触发同步，而不是等待下一个轮询间隔，因此几秒内就能收到新邮件通知。请尽量缩短此列表——每个条目都会在容器整个生命周期内占用一个打开的 IMAP 连接。最佳做法是这里只添加 "INBOX"，或者完全省略此项并依靠定期轮询。

trash_folder： AI Agent 调用 delete_mail 工具时，mail-shadow-mcp 用来移动邮件的 IMAP 文件夹。此文件夹必须已存在于邮件服务上。如果未设置此项，delete_mail 会返回错误且不执行任何操作——这是安全的默认行为。垃圾箱中的邮件会自动从所有 MCP 查询结果（搜索、近期活动、会话）中排除，因此 Agent 再也无法看到这些邮件，无论该文件夹是否包含在同步配置中。注意：如果你将 trash_folder 更改为其他文件夹名称，旧垃圾箱将不再被排除，其中的内容会在下次同步后重新显示给 Agent。切换前，请务必手动清空旧文件夹。

http_bearer_token： 用于保护 MCP HTTP 端点的密钥令牌。AI Agent 发出的每个请求都必须包含 Authorization: Bearer <token>。如果不设置，任何能够访问该端口的人都可以连接到你的 MCP 服务——因此，使用 http 传输时务必设置此项。使用以下命令生成安全的随机令牌：

# Linux / macOS / WSL
openssl rand -hex 32

# Windows PowerShell
[System.Convert]::ToBase64String((1..32 | ForEach-Object { [byte](Get-Random -Max 256) }))

将输出复制到配置中，并将相同的值传给 AI Agent（参见步骤 4）。

步骤 3 — 启动容器

docker run -d \
  --name mail-shadow-mcp \
  --restart unless-stopped \
  -v ./config:/config:ro \
  -v ./data:/data \
  -e WORK_IMAP_PASS=your_password_here \
  -p 8080:8080 \
  ghcr.io/dryas/mail-shadow-mcp:latest

现在可以通过 http://localhost:8080/mcp 访问 MCP 服务。

每次发布时，都会将预构建的多架构镜像（linux/amd64、linux/arm64）发布到 GitHub Container Registry：

docker pull ghcr.io/dryas/mail-shadow-mcp:latest

步骤 4 — 连接 AI Agent

由于我们使用 Docker 运行，MCP 服务可通过 HTTP 访问——Claude Desktop 也支持这种方式，不只是远程 Agent。将以下内容添加到 Agent 的配置中：

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "mail_shadow": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

如果 mail-shadow-mcp 运行在其他机器上，请将 localhost 替换为服务的 IP 地址或主机名。

Hermes Agent（config.yaml）：

  mail-shadow:
    url: http://localhost:8080/mcp
    headers:
      Authorization: Bearer your-secret-token

OpenClaw（~/.openclaw/openclaw.json）：

{
  "mcp": {
    "servers": {
      "mail_shadow": {
        "url": "http://localhost:8080/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer your-secret-token"
        }
      }
    }
  }
}

替代方案：本地 stdio（预编译二进制文件，无需 Docker）

如果你选择直接运行二进制文件而不是使用 Docker，请使用 command 格式：

{
  "mcpServers": {
    "mail_shadow": {
      "command": "/path/to/mail-shadow-mcp",
      "args": ["serve", "--config", "/path/to/config.yaml"]
    }
  }
}

完成——现在你的 AI 可以安全地搜索和阅读邮件了。

---

安全性：删除从来都不是真正删除

mail-shadow-mcp 为 AI Agent 提供了 delete_mail 工具，但这个工具绝不会执行破坏性的 IMAP 命令。Agent 调用该工具时，具体会发生以下情况：

1. MCP 服务在本地数据库中查找这封邮件。
2. 它会打开一个短暂的 IMAP 连接，并执行 IMAP MOVE——将邮件移至你在 config.yaml 中指定的 trash_folder（例如 "llm_delete"）。
3. 本地数据库条目会被移除，而垃圾邮件文件夹会被永久排除在所有 MCP 查询结果之外——Agent 再也看不到移出的邮件，无论该文件夹是否已同步。
4. 邮件仍会完整保留在 IMAP 服务上，安全地存放在垃圾邮件文件夹中。你可以随时自行查看、恢复或永久删除它。

AI Agent 无法直接访问 IMAP。它不能清除邮件、清空文件夹，也不能执行此受控移动操作以外的任何写入命令。如果某个账户未配置 trash_folder，delete_mail 会返回错误并且不执行任何操作。

---

技术深入解析

MCP 工具

工具	描述
list_accounts_and_folders	列出所有已同步的账户及其文件夹
get_recent_activity	获取最近的 N 封邮件，可选筛选条件（is_read、has_attachments、分页）
get_email_content	获取单封邮件的完整正文、已读／已回复状态和附件列表
search_emails	使用 FTS5 进行全文搜索，可按主题／发件人／日期／文件夹／is_read／sent_by 筛选
get_thread	获取与指定邮件属于同一会话的所有邮件，并按日期升序排列
download_attachments	从 IMAP 获取附件文件并保存到磁盘
get_download_link	为附件生成临时 HTTP 下载 URL（可选备用方案）
delete_mail	通过将邮件移至已配置的垃圾邮件文件夹来软删除邮件（IMAP MOVE，不会永久删除）

功能概览

• 本地影子数据库 — 邮件会同步到本地 SQLite 数据库；AI Agent 不会直接连接你的 IMAP 服务
• 只读同步 — 同步引擎只执行读取命令（SELECT、UID FETCH）；绝不会向你的邮件服务发送 STORE、APPEND 或 EXPUNGE
• 增量同步 — 只获取 UID 大于已知最新 UID 的邮件
• 全文搜索 — 使用 SQLite FTS5 索引快速搜索正文
• 多账户 — 可同时同步任意数量的 IMAP 账户
• IMAP IDLE — 可选的实时推送通知；几秒内即可检测到新邮件，无需等待下一次轮询
• 已读／已回复状态 — 从 IMAP 同步 is_read 和 is_replied 标记，并将其作为筛选条件提供
• 会话视图 — get_thread 通过 Message-ID／In-Reply-To 标头遍历完整邮件对话
• 分页结果 — 所有列表工具都会返回 total_count，方便 Agent 分页浏览大型结果集
• 按需获取附件 — 只有在明确请求时，才会从 IMAP 获取附件文件
• 灵活的传输方式 — 本地工具（Claude Desktop）使用 stdio，远程和 Docker 部署可使用 http（StreamableHTTP）或 sse
• 适用于 Docker — 每次发布时都会将官方多架构镜像（linux/amd64、linux/arm64）发布到 ghcr.io

完整配置参考

sync_interval_min: 15

database:
  path: "data/mail.db"      # path to the local SQLite shadow database

attachment_dir: "data/attachments"  # base directory for downloaded attachments

# Optional: log file and level. Omit log_file to write to stderr (default).
# log_file: "logs/mail-shadow-mcp.log"  # append mode; directory is created automatically
# log_level: info                        # debug | info (default) | warn | error
# log_format: text                       # text (default) | json

# MCP transport mode.
# stdio (default) — stdin/stdout, used by Claude Desktop and most local tools.
# http            — StreamableHTTP, recommended for Docker and remote deployments.
# sse             — legacy SSE transport (prefer http unless your client requires SSE).
# transport: stdio
# http_addr: ":8080"                      # bind address for http/sse (default: :8080)
# http_base_url: "http://localhost:8080"  # sse only: externally reachable base URL
# http_bearer_token: ""                  # recommended: set a secret token to protect the HTTP endpoint
                                         # generate one with: openssl rand -hex 32

# Optional: lightweight HTTP server for temporary attachment download links.
# fileserver_port: 8787               # TCP port to listen on (disabled if omitted)
# fileserver_ttl_min: 15              # minutes before a link expires (default: 15)
# fileserver_host: "localhost"        # hostname/IP shown in generated URLs

accounts:
  - id: "[email protected]"
    host: "imap.example.com"
    port: 993
    username: "[email protected]"
    password: "$WORK_IMAP_PASS"     # or plain text; prefix with $ to read from env var
    tls_mode: tls                   # tls (default, implicit TLS, port 993)
                                    # starttls (STARTTLS upgrade, port 143)
                                    # none (no encryption — localhost/testing only)
    tls_skip_verify: false          # set true for self-signed certificates
    folders: ["INBOX", "Archive"]   # optional: omit to sync all folders
    # idle_folders: ["INBOX"]       # optional: folders watched via IMAP IDLE for instant new-mail notification
    # trash_folder: "llm_delete"    # optional: target folder for delete_mail (soft-delete via IMAP MOVE)

Docker Compose

services:
  mail-shadow-mcp:
    image: ghcr.io/dryas/mail-shadow-mcp:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./config/config.yaml:/config/config.yaml:ro   # your config — mount read-only
      - ./data:/data                                  # persistent DB + attachments
    environment:
      - WORK_IMAP_PASS=your_password_here             # referenced as $WORK_IMAP_PASS in config

将密码作为环境变量： 在 config.yaml 中，你可以使用 $ENV_VAR 引用密码——服务会在启动时解析这些变量。通过 docker-compose 中的 environment: 或使用 docker run 时的 -e 传入密码。这样，配置文件中就不会出现明文密码。

TLS 模式

tls_mode	端口	描述
tls	993	隐式 TLS（默认）
starttls	143	STARTTLS 升级
none	143	不加密——仅用于本地主机／测试

设置 tls_skip_verify: true 即可接受自签名证书。

身份验证（Bearer Token）

使用 http 或 sse 传输时，务必设置 http_bearer_token——否则，任何能够访问该端口的人都可以访问 MCP 端点。

生成一个密码学安全的令牌：

# Linux / macOS / WSL
openssl rand -hex 32

# PowerShell
[System.Convert]::ToBase64String((1..32 | ForEach-Object { [byte](Get-Random -Max 256) }))

IMAP IDLE（实时推送）

默认情况下，mail-shadow-mcp 每隔 sync_interval_min 分钟轮询一次新邮件。对于需要近乎即时通知的文件夹，请启用 IMAP IDLE：

accounts:
  - id: "[email protected]"
    # ...
    idle_folders: ["INBOX"]   # IDLE runs on top of regular polling

• 为 idle_folders 中的每个条目打开一个专用 IMAP 连接
• 服务器发送 EXISTS 通知时，会立即触发同步
• 其他文件夹继续按原方式定期轮询
• 如果服务器不支持 IDLE，则自动回退到轮询
• 连接持续出错时采用指数退避（30 s → 5 min）

附件下载服务器

可选的内置 HTTP 服务器允许 AI Agent 为附件文件生成临时、单次使用的下载链接——当 Agent 无法通过常规渠道传输文件时，这种方式很有用。

在 config.yaml 中启用：

fileserver_port: 8787        # TCP port to listen on
fileserver_ttl_min: 15       # minutes before a link expires (default: 15)
fileserver_host: "localhost" # hostname/IP shown in generated URLs

从源代码构建

make build          # current platform
make release        # cross-compile for all platforms into dist/

需要 Go 1.25+。

CLI 命令

除了作为 MCP 服务运行外，mail-shadow-mcp 还提供了一些 CLI 命令，可用于手动操作、编写脚本或调试——无需 AI Agent。

触发一次性同步（将新邮件抓取到本地数据库后退出）：

./mail-shadow-mcp sync

查询本地数据库（输出为以换行符分隔的 JSON，适用于 jq 管道）：

# Search by subject and body keyword
./mail-shadow-mcp query --subject "invoice" --body "Q1"

# Full-text search with attachment filter
./mail-shadow-mcp query -q "budget" --attachments only

# Most recent emails, paginated
./mail-shadow-mcp query --recent --limit 10 --offset 10

下载指定邮件的附件，邮件 ID 格式为 account:folder:uid：

./mail-shadow-mcp attachments --id "[email protected]:INBOX:42"

---

许可证

Apache 2.0 — 详情请参阅 LICENSE。
版权所有 (c) 2026 Benjamin Kaiser。