IMAP Mail

imap-mcp

一个小型 MCP 服务，让 AI 助手 （例如 Claude Desktop）能够读取 IMAP 邮箱并创建草稿。它最初是为 Raspberry Pi 上的 Hetzner 邮箱和 iCloud 账户编写的，但适用于任何支持 IMAPS（端口 993）的 IMAP 服务。

**状态：**个人项目，按现状发布。它适用于可信的家庭 网络，不适用于开放互联网。请参阅安全和 SECURITY.md。

功能

工具：list_accounts、list_folders、list_messages、search_messages、 read_message、mark_read、create_draft。每个工具都有一个 account 参数；如果省略， 则使用第一个配置的账户。

• 读取为只读操作：邮件使用 BODY.PEEK 获取，默认不会将邮件标记为 已读、移动或删除。
• 对现有邮件的唯一写入操作是设置 \Seen 标记；可通过 mark_read 设置，也可在启用后由 read_message 自行设置。请参阅已读状态。
• 有意不提供发送功能。create_draft 会将草稿存入 草稿文件夹；你需要在自己的邮件客户端中检查并发送。
• 草稿可以包含附件（PDF、PNG、JPEG），这些附件取自一个已配置的文件夹 （默认关闭 ATTACHMENT_DIR）。请参阅附件。
• 发件人仅限账户地址及已配置的别名 （允许使用 MAIL_ALIASES 和 *@example.com 这类通配符）。回复时会自动选择 原邮件的收件地址。
• 每封邮件最多加载 2 MB；邮件被截断时，read_message 会报告 message_truncated。
• 每个账户的一个 IMAP 连接会在多次调用之间重复使用。
• 邮件内容会被视为不可信数据（请参阅服务说明和 安全）。

要求

• Python 3.10+
• 一个在需要时使用应用专用密码的 IMAP 账户（iCloud、Gmail 等）
• 服务本身需要 mcp 和 uvicorn（请参阅 requirements.txt）；邮件 逻辑仅使用标准库。

1. 安装

git clone https://github.com/<you>/imap-mcp.git
cd imap-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

cp config.env.example config.env
chmod 600 config.env
$EDITOR config.env          # user, password, aliases

.venv/bin/python -m unittest discover -s tests   # offline tests
.venv/bin/python server.py --check                # test the real IMAP connections

--check 会为每个账户打印一行，例如 OK [hetzner] [email protected] @ mail.your-server.de, Drafts: INBOX.Drafts, Senders: …。

2a. 通过 SSH 连接（stdio，推荐）

客户端会按需通过 SSH 启动服务：无需开放端口，无需令牌，并由 SSH 加密。 请使用无需输入密码短语的密钥（必须能成功运行 ssh -o BatchMode=yes host echo ok）。claude_desktop_config.json 示例：

{
  "mcpServers": {
    "mail": {
      "command": "ssh",
      "args": [
        "-T", "-o", "BatchMode=yes", "-o", "ServerAliveInterval=30",
        "user@your-host",
        "/path/to/imap-mcp/.venv/bin/python",
        "/path/to/imap-mcp/server.py"
      ]
    }
  }
}

2b. 替代方案：局域网上的 HTTP 服务

适用于多台机器需要使用此服务的情况。

python3 -c 'import secrets; print(secrets.token_urlsafe(32))'   # generate a token
# in config.env: MCP_AUTH_TOKEN=<token>

scripts/make-cert.sh        # self-signed certificate for this host
# in config.env:
# TLS_CERT=/path/to/imap-mcp/certs/server.crt
# TLS_KEY=/path/to/imap-mcp/certs/server.key

sudo cp imap-mcp.service /etc/systemd/system/    # adjust User= and the paths first
sudo systemctl daemon-reload
sudo systemctl enable --now imap-mcp

端点为 https://<host>:8765/mcp，并要求提供 Authorization: Bearer <token>。 如果没有 --host，服务只会监听 127.0.0.1；systemd 单元会传入 --host 0.0.0.0（所有接口），因此如果你有需要，可以将其改为局域网地址。 除普通 HTTP 请求外的请求（例如 WebSocket）都会被拒绝。 如果没有 TLS_CERT/TLS_KEY，服务会继续以明文运行并记录警告。证书有效期为 730 天；之后请再次运行 make-cert.sh 并重新分发证书。

只支持 stdio 的客户端可以使用 mcp-remote 桥接程序（需要 Node.js）。Node 必须信任自签名证书，因此请将 NODE_EXTRA_CA_CERTS 指向 客户端机器上的 server.crt 副本：

{
  "mcpServers": {
    "mail": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<host>:8765/mcp",
               "--header", "Authorization:${AUTH}"],
      "env": { "AUTH": "Bearer <token>",
               "NODE_EXTRA_CA_CERTS": "/path/on/the/client/server.crt" }
    }
  }
}

Claude 设置中的自定义连接器无法用于局域网地址，因为它们会从 Anthropic 的云端发起连接。

2c. 替代方案：Docker（本地 stdio）

amd64 和 arm64 的容器镜像发布于 ghcr.io/buzzer/imap-mcp；该服务在 MCP 注册表中的登记名称为 io.github.buzzer/imap-mcp。客户端会按需启动容器，并通过环境变量传入配置：

{
  "mcpServers": {
    "mail": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "IMAP_HOST", "-e", "MAIL_USER", "-e", "MAIL_PASSWORD",
               "ghcr.io/buzzer/imap-mcp:latest"],
      "env": {
        "IMAP_HOST": "imap.example.com",
        "MAIL_USER": "[email protected]",
        "MAIL_PASSWORD": "app-password"
      }
    }
  }
}

配置中的每个键都可以用同样的方式传入。对于多个账户，挂载配置文件会更方便： -v /path/to/config.env:/config.env:ro -e MAIL_MCP_CONFIG=/config.env。容器以 UID 10001 运行，因此该用户必须能读取此文件。对于附件，请以只读方式挂载文件夹，并将 ATTACHMENT_DIR 设置为容器内的路径。

配置

所有键请参阅 config.env.example（MAIL_USER、MAIL_PASSWORD、MAIL_ADDRESS、 MAIL_FROM_NAME、MAIL_ALIASES、IMAP_HOST、IMAP_PORT、IMAP_TIMEOUT、 DRAFTS_FOLDER、ATTACHMENT_DIR、ATTACHMENT_MAX_BYTES、ATTACHMENT_MAX_TOTAL_BYTES、 ATTACHMENT_MAX_COUNT、MARK_READ_ON_READ、BCC_SELF、ACCOUNTS、ACCOUNT_NAME、MCP_AUTH_TOKEN、 TLS_CERT、TLS_KEY）。对于其他账户，最多到 ATTACHMENT_MAX_COUNT 的账户键可以加上 <NAME>_ 前缀；其余键均为全局设置。每个键也可以设为环境变量；使用 MAIL_MCP_CONFIG 或 --config 选择其他配置文件。

其他账户：iCloud

ACCOUNTS=hetzner,icloud
ICLOUD_MAIL_USER=first.last                # login, usually the part before @icloud.com
[email protected]
ICLOUD_MAIL_PASSWORD=abcd-efgh-ijkl-mnop   # app-specific password

密码应为从 account.apple.com 获取的 App 专用密码（登录与安全 → App 专用密码），而不是 Apple ID 密码。 账户名称为 icloud 时，预配置的服务器为 imap.mail.me.com:993；账户名称为 hetzner 时，预配置的服务器为 mail.your-server.de:993。其他账户名称都需要设置 <NAME>_IMAP_HOST；服务不会猜测主机，因此不会把密码发送给错误的服务商。

已读状态

为了让本地邮件客户端显示助手已查看过哪些邮件，read_message 可以为其返回的每封邮件设置 \Seen 标记：

• 在 config.env 中设置 MARK_READ_ON_READ=true，即可为所有账户启用此功能 （一个全局选项，默认关闭）。没有按调用或按账户设置的选项。
• 只有 read_message 会执行此操作。列出和搜索操作仅显示邮件头，不会更改标记；对于以其他方式处理的邮件，仍可使用 mark_read。
• 结果包含 unread（读取前的状态）和 marked_read。如果无法设置标记，仍会返回邮件，且 marked_read 为 false。
• 除 \Seen 外，不会设置任何标记；已读邮件不会被更改。

密送给自己

在 config.env 中设置 BCC_SELF=true（适用于所有账户的全局选项，默认关闭）后，create_draft 会将草稿的发件人地址添加为密送收件人，这样已发送邮件的副本也会进入该邮箱。此处使用的地址就是实际发件人地址（账户地址或别名，见 from_address）。如果该地址已在 To、Cc 或 Bcc 中，则不会重复添加。结果会显示最终的 bcc，而 list_accounts 会报告 bcc_self。

附件

create_draft 接受 attachments，即一组相对于 ATTACHMENT_DIR 的文件路径。只有在 config.env 中设置了该键后，此功能才会启用 （list_accounts 会按账户显示 attachments_enabled）。以下规则均由服务强制执行：

• 仅允许 .pdf、.png、.jpg 和 .jpeg；文件内容必须以对应的魔数开头（改名的文件会被拒绝）；
• 文件必须位于 ATTACHMENT_DIR 下：绝对路径、..、符号链接以及隐藏文件或文件夹（.env、.ssh 等）均会被拒绝；
• 最多允许 ATTACHMENT_MAX_COUNT 个文件（默认 5 个），每个文件不超过 ATTACHMENT_MAX_BYTES（默认 10 MB），合计不超过 ATTACHMENT_MAX_TOTAL_BYTES（默认 15 MB）；
• 只有在所有附件都通过检查后，草稿才会被保存；模型永远不会看到文件内容，只会看到文件名。

建议的设置

使用专用的扁平文件夹，其中只放置你愿意附加的文件。 模型可以附加其中的所有文件。

mkdir -p ~/mail-attachments
chmod 700 ~/mail-attachments

ATTACHMENT_DIR=/home/<user>/mail-attachments

• 通过 SSH 使用 stdio 传输时，服务会以 SSH 用户身份读取文件。
• 工具调用中的路径相对于该文件夹，例如 invoice-2026-10.pdf 或 invoices/2026/invoice-2026-10.pdf；不接受绝对路径。
• 服务只读取文件。请自行将文件放入其中（scp file.pdf host:mail-attachments/、 rsync、Syncthing 或 Samba 共享），然后让助手按名称附加文件。
• 多个账户可以使用带有相应前缀的独立文件夹，例如 ICLOUD_ATTACHMENT_DIR=/home/<user>/mail-attachments-icloud。
• 使用 systemd 单元（ProtectHome=read-only）时，服务用户需要有读取权限； 最简单的做法是将文件夹放在 /home 之外，例如 /opt/imap-mcp/attachments。
• 删除不再需要的文件。

安全

• config.env 包含邮箱密码：执行 chmod 600，切勿提交该文件（如果其他用户可读取该文件，服务会发出警告）。
• 邮件内容是不可信文本。服务说明会告知模型不要遵循邮件中包含的请求。由于无法发送或删除任何内容，可能造成的损害仅限于草稿，以及向模型泄露邮件内容。
• HTML 邮件会转换为文本供模型读取，并移除读者无法看到的内容（display:none、hidden、opacity:0、折叠的预览文本、script/style/head），从而清除最常见的隐形提示注入藏匿位置。仅仅不可读的文本（白底白字、在子元素上设置的小字体）仍会传递给模型，因此这只是缓解措施，并非万无一失。
• 含有控制字符（CR/LF）的搜索词会被拒绝，因此无法注入额外的 IMAP 命令。含有换行符的收件人地址也会被拒绝。
• HTTP 传输使用单个静态 bearer token，且没有速率限制。仅在可信网络中通过 TLS 使用；如果令牌泄露，请轮换令牌。
• 失败的 HTTP 身份验证尝试会记录客户端 IP；工具调用（账户、文件夹、UID）会被记录，但不包含邮件内容。

已知限制

• 草稿仅支持纯文本。引用回复的署名行 （“Am … schrieb …:”）和占位主题“(kein Betreff)”为德语。
• 附件仅限来自一个文件夹的 PDF/PNG/JPEG；无法移动或删除邮件；唯一可设置的标志是 \Seen（通过 mark_read）。
• 仅在 Hetzner（Dovecot）和 iCloud 上经过测试。

开发

python -m unittest discover -s tests    # no network and no MCP SDK needed

发布

该服务以容器映像的形式分发在 ghcr.io/buzzer/imap-mcp，并以 io.github.buzzer/imap-mcp 列入 MCP 注册表。当推送版本标签时，publish 工作流（.github/workflows/publish.yml）会更新这两处：

1. 在 server.json 的两个位置设置新版本：version，以及 packages[0].identifier 末尾的映像标签。
2. 提交，然后打标签并推送：git tag v0.3.0 && git push origin main v0.3.0。 如果标签与 server.json 中的版本不一致，工作流会失败。
3. 检查结果： curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.buzzer/imap-mcp"

需要了解的事项：

• 注册表只存储元数据，并通过 Dockerfile 中的映像标签 io.modelcontextprotocol.server.name 验证所有权；该标签必须与 server.json 中的 name 保持一致。
• 工作流使用 GitHub OIDC 登录注册表，因此无需密钥或令牌；命名空间 io.github.buzzer 与 GitHub 账号关联。
• 用户希望在客户端中看到的新配置键，既要添加到 server.json 的 environmentVariables 中，也要添加到 config.env.example 中。
• 工作流中按版本和 SHA-256 固定了 mcp-publisher （MCP_PUBLISHER_VERSION、MCP_PUBLISHER_SHA256）。如需更新，请从 发布版本的 registry_<version>_checksums.txt 中获取 mcp-publisher_linux_amd64.tar.gz 的校验和。
• 可使用 mcp-publisher validate 在本地检查 server.json。

许可证

MIT