your-mail-mcp

你的邮件里早已有答案：预订参考号、门禁密码、发票、保修期，以及人们白纸黑字许下的承诺。这个服务器让你的 AI 助手能找到它们。

可以问它这类问题：

• "找到六月渡轮的预订参考号。"

• "去年夏天酒店发来的 Wi-Fi 密码是什么？"

• "会计师关于增值税回复了什么，是什么时候回的？"

• "把我和施工方之间关于屋顶的往来邮件按顺序整理出来，并总结谁承诺了什么。"

• "今天早上所有账户收到的邮件里，有哪些真正需要我处理？"

可以这样使用：

• 能理解问题的搜索。 对你的全部历史邮件进行全文搜索，所有账户汇总在一个索引里，用你思考的方式表达，而不是按照搜索语法来写。

• 在手机上分拣邮件。 无论你在哪里，都能收到一份晨间摘要，汇总夜间到达的邮件，垃圾邮件已被过滤掉。

• 把邮件作为其他工作的上下文。 从邮件线索中提取客户需求，带入你的编程或写作会话，而不用重新输入。

• 可以放心持续运行的智能体。 这个服务器只能读取。一封到达你助手的恶意邮件只会被读取，仅此而已，因为这里根本没有发送、删除和移动这些操作。这让定时摘要和常驻智能体可以安心运行。

安装只需要两个文件和一条 docker compose up -d 命令——参见运行方式。

这是一个自托管的 MCP 服务器，让 MCP 客户端（Claude，或任何支持带 OAuth 的流式 HTTP MCP 的客户端）获得你邮件的只读访问权限。它用 mbsync 将一个或多个 IMAP 账户镜像到本地 maildir，用 notmuch 为它们建立索引，并基于该索引响应工具调用。

在这张图中，邮件始终只从左向右流动。服务器朝服务商方向发出的唯一箭头，是启动时的一次 IMAP LIST 命令，用来确认该服务器如何命名其垃圾邮件和已删除邮件文件夹；它从不选择邮箱，也从不取回邮件。图表的源文件是 docs/diagrams/how-it-works.html。

它不能做什么

只读特性是架构内置的。

镜像是纯拉取模式。为每个账户生成的 mbsync 配置都带有 Sync Pull、Create Near、Remove None、Expunge None——该配置中没有任何内容可以将更改推回服务器、删除或清除邮件。

Go 代码中唯一的 IMAP 操作就是 LIST，启动时对每个账户执行一次，用来确定各账户的垃圾邮件和已删除邮件文件夹（参见服务商说明和故障排查）。该连接只做登录、列出邮箱、然后退出。它从不选择邮箱，也从不取回邮件。

没有发送、删除、移动或打标签功能。附件会在 show 和 thread 中列出，并由 attachment 工具以只读方式提供，一次一个部分，上限为 5MB。更大的部分通过 GET /attachment/{id}/{part} 以原始方式提供，需要持有者令牌或该工具在拒绝超大附件时返回的短期签名链接进行身份验证。整个进程中的任何部分都不具备对任何账户的写权限。

十个工具，全部只读：

search、ids、files 和 count 接受 notmuch 查询（from:、to:、subject:、tag:、folder:、date:2026-01-01..2026-06-30，可用 and/or/not 组合），可选的 account 参数用于限定到某个账户，还可以通过 include_excluded 包含垃圾/已删除邮件。

Related MCP server: notmuchproxy

运行方式

有三种运行方式，区别只在一件事：谁能访问服务器。从方案 1 开始，只有在需要时才升级。它们都只做了默认程度的安全加固——更深入的内容在下方安全加固一节，之所以单独分开，是为了让你先把服务器跑起来。

服务器以容器镜像形式发布在 ghcr.io/wildsurfer/your-mail-mcp，由 CI 为 amd64 和 arm64 构建并发布。无需编译任何东西，每种方案都以相同方式开始——在一个空目录里放两个文件：

mkdir your-mail && cd your-mail
curl -fsSLO https://raw.githubusercontent.com/wildsurfer/your-mail-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/wildsurfer/your-mail-mcp/main/accounts.example.json -o accounts.json

用你的账户信息编辑 accounts.json（参见账户文件），然后在 compose.yaml 旁边放一个 .env 文件，填入它所引用的密钥：

# .env
OAUTH_PASSPHRASE=pick-a-long-one-you-can-type-on-a-smartphone
WORK_PASS=your-gmail-app-password
PERSONAL_PASS=your-icloud-app-specific-password

在方案 2 和方案 3 中，OAUTH_PASSPHRASE 是互联网与你的邮件之间唯一的凭据。请妥善保管。

这两个文件保存着你的邮件密码。如果你把这个目录纳入版本控制，或备份到离开本机的地方，请同样妥善处理。

方案 1 ——在本机运行，仅供本机使用

服务器绑定到回环地址。本机之外的任何设备都无法访问它，因此无需配置 TLS，也无需拥有域名。你的命令行工具可以使用它，但智能手机不行。

在 .env 中加一行：

PUBLIC_URL=http://127.0.0.1:8080

然后启动它：

docker compose up -d
docker compose logs -f          # watch the first sync

首次同步会填充 maildir，在大型邮箱上会花一些时间。它故意做得比可以做到的速度慢，一次只发一条 IMAP 命令，因为服务商会限流。没有单独的初始化步骤。

Claude Code

claude mcp add --transport http your-mail http://127.0.0.1:8080/mcp

然后在 Claude Code 中运行 /mcp，选择 your-mail 并完成认证。浏览器会打开同意页面，只询问一件事：你的 OAUTH_PASSPHRASE。在完成这一步之前，claude mcp list 会显示 Needs authentication。

Codex

codex mcp add your-mail --url http://127.0.0.1:8080/mcp
codex mcp login your-mail

codex mcp list 会显示认证状态。如果登录成功后工具仍未出现在会话中，那是 Codex 的一个已知 bug：OAuth 凭据被获取后从未被使用（openai/codex#20009）。在修复之前，请使用下面的桥接方案。

mcp-remote 自己完成 OAuth 流程，并通过 stdio 重新暴露服务器，所有 MCP 客户端都支持 stdio：

# ~/.codex/config.toml
[mcp_servers.your-mail]
command = "npx"
args = ["-y", "mcp-remote", "http://127.0.0.1:8080/mcp"]

首次运行时它会打开同一个同意页面，并缓存令牌。

方案 2 ——在本机运行，可从任何地方访问

服务器相同，只是额外加一个东西给它提供公网 HTTPS 地址。你的邮件仍然留在本机，家庭网络上没有任何监听端口，因为隧道是主动向外拨号的。智能手机和桌面应用需要这个方案：自定义连接器由厂商的服务器获取，因此它无法访问私有地址。

使用 Tailscale（无需域名）

一条命令，macOS 和 Linux 上相同，无需拥有域名就能得到一个 HTTPS 主机名。

tailscale funnel --bg 8080

--bg 让它在重启后继续运行。它会打印公网 URL，形如 https://your-machine.your-tailnet.ts.net。这就是要使用的主机名：

# .env
PUBLIC_URL=https://your-machine.your-tailnet.ts.net

docker compose up -d

Funnel 需要 HTTPS 证书，并且需要为你的 tailnet 启用 Funnel 节点属性；CLI 会在第一次时提示添加策略行，其余操作在你的管理控制台中进行。tailscale funnel status 显示已暴露的内容，tailscale funnel --https=443 off 将其关闭。

使用 Cloudflare（你拥有域名，且已托管在 Cloudflare）

如果你想用自己域名上的主机名而不是 .ts.net 域名，就用这个方案。下面的 mail.example.com 是你的域名，且已添加到你的 Cloudflare 账户——Cloudflare 不会为命名隧道分配主机名。

cloudflared tunnel login
cloudflared tunnel create your-mail

create 会打印隧道的 UUID 和刚写入的凭据文件：

Tunnel credentials written to /Users/you/.cloudflared/f9e2…-… .json
Created tunnel your-mail with id f9e2…-…

在下面使用那个确切路径；如果弄丢了 UUID，cloudflared tunnel list 会再次打印。将主机名路由到隧道，然后写入 ~/.cloudflared/config.yml：

cloudflared tunnel route dns your-mail mail.example.com

tunnel: your-mail
credentials-file: /Users/you/.cloudflared/f9e2….json   # the path create printed
url: http://localhost:8080

cloudflared tunnel run your-mail

让它持续运行：在 Linux 上，执行 sudo cloudflared service install。在 macOS 上，通过 Homebrew 安装，并使用 brew services start cloudflared，因为 sudo 安装方式会在 root 用户的主目录下查找证书，找不到 cloudflared tunnel login 写入你主目录的那份。

然后在 .env 中设置 PUBLIC_URL=https://mail.example.com，并执行 docker compose up -d。

无论哪种方式

PUBLIC_URL 必须与你输入客户端的内容完全一致。服务器在其 OAuth 元数据中将 PUBLIC_URL + /mcp 发布为 resource，不一致是连接器拒绝添加的最常见原因。

在智能手机上开始之前需要知道一件事：Claude 和 ChatGPT 都不允许从智能手机应用添加连接器。 你需要在网页端（或 Claude 的桌面应用）添加一次，然后它就会出现在你的智能手机上。试图在智能手机上完成设置只会浪费你的时间。

Claude ——在网页或桌面端添加，然后在智能手机上使用

1. 在 claude.ai 或 Claude Desktop 中，进入 设置 → 连接器，点击连接器旁边的 +，或点击 添加自定义连接器。

2. 给它一个名称和 URL <PUBLIC_URL>/mcp。高级 OAuth 字段留空：此服务器会动态注册客户端。

3. Claude 会打开同意页面。输入你的 OAUTH_PASSPHRASE。

4. 打开智能手机上的 Claude 应用。连接器已经在那里了，工具可在聊天中使用。在编辑器（composer）的工具或连接器菜单中为某个对话开启它。

ChatGPT ——在网页端添加，然后在智能手机上使用

自定义 MCP 连接器位于开发者模式之下，需要 Pro、Plus、Business、Enterprise 或 Education 账户，且仅在网页端可用。

1. 在网页版 ChatGPT 中，打开 设置 → 安全与登录，开启开发者模式。在 Business 和 Enterprise 工作区中，管理员可能必须先允许该功能。

2. 为远程 MCP 服务器添加连接器，并为其提供 URL <PUBLIC_URL>/mcp，认证方式选择 OAuth。ChatGPT 支持动态客户端注册，因此无需粘贴任何内容。

3. 使用你的 OAUTH_PASSPHRASE 批准同意页面。

4. 在智能手机上打开 ChatGPT，并在聊天中启用该连接器。

这些菜单会变动。如果上述名称与你看到的不一致，请在设置中查找开发者模式，然后找到按 URL 添加连接器的位置。

ChatGPT 会在移动端禁用某些 MCP 写入操作。这对本服务器没有影响，因为该服务器根本没有写入操作。

Claude Code

claude mcp add --transport http your-mail https://your-host/mcp

Codex

codex mcp add your-mail --url https://your-host/mcp
codex mcp login your-mail

场景 3 — 部署在 VPS 上，可从任何地方访问

当你想让镜像无论你的机器是否开机都保持在线时，选择此方案。它每月花费几美元，并且有一个真正的权衡：你的邮件的完整明文副本会移到租用的磁盘上，应用密码也在同一环境中。在选择之前，请阅读安全。

安装方式为场景 1 加上一个隧道，运行在别人的计算机上。无需开放端口，无需配置 DNS，无需管理证书。

在一台全新的 Debian 或 Ubuntu 机器上：

# 1. Docker
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER && newgrp docker

# 2. The two files, and your accounts
mkdir your-mail && cd your-mail
curl -fsSLO https://raw.githubusercontent.com/wildsurfer/your-mail-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/wildsurfer/your-mail-mcp/main/accounts.example.json -o accounts.json
$EDITOR accounts.json             # your accounts
$EDITOR .env                      # OAUTH_PASSPHRASE and the account passwords

# 3. A public address, exactly as in case 2
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
tailscale funnel --bg 8080        # prints your https://….ts.net hostname

# 4. Put that hostname in .env, then start
echo "PUBLIC_URL=https://your-machine.your-tailnet.ts.net" >> .env
docker compose up -d
docker compose logs -f

PUBLIC_URL 放在最后，因为直到步骤 3 打印出主机名之前，你都不知道它是什么。

连接客户端与场景 2 完全相同。

compose.yaml 中的 restart: unless-stopped 会在重启后恢复容器。使用 folders 工具检查其状态，该工具会报告每个账户的最后同步时间和最后错误，或者使用 docker compose logs --tail=50。

现在去阅读加固。一台可以用密码 SSH 登录、存有你的邮件副本的 VPS，比完全不运行这个服务更糟糕。

加固

这些都不是让服务器工作所必需的，这就是为什么它们不在安装步骤中。按它们能给你带来的收益排序。场景 1 不需要其中任何一项。

选择一个真正的强密码短语。 OAUTH_PASSPHRASE 是整扇门。一次错误猜测会让攻击者花费一秒钟，而且猜测是串行化的，所以并行运行它们没有帮助，但这两点都救不了短密码短语。选择一个你仍然能在智能手机上输入的足够长的密码短语。

锁定 SSH（场景 3）。一台租用的机器，带有密码登录和你的邮件副本，是本文档中最糟糕的组合。以 root 身份，在做其他任何事情之前：

adduser mail && usermod -aG sudo mail
rsync --archive --chown=mail:mail ~/.ssh /home/mail
sed -i 's/^#\?PermitRootLogin.*/PermitRootLogin no/; s/^#\?PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config
systemctl restart ssh

然后以 mail 用户而不是 root 身份进行安装。

关闭你不使用的端口（场景 3）。使用隧道时你根本不需要入站端口，所以：

sudo ufw allow OpenSSH && sudo ufw --force enable

限制谁能访问连接器。 如果唯一与你的服务器通信的是 Claude 应用中的自定义连接器，那么该流量来自 Anthropic 公布的出口网段 160.79.104.0/21，你可以在隧道或防火墙处拒绝其他所有流量。如果你还在笔记本电脑上使用 Claude Code 或 Codex，则不要这样做，因为它们会从你所在的位置连接。

备份卷，或者接受重新同步。 compose.yaml 将 maildir 和索引保存在命名卷中。其中没有任何独特的内容——它们都还在你的邮件服务器上——但重新下载大型邮箱需要一段时间，并且会惹恼限流的提供商。

了解密码短语不能保护什么。 它只保护 MCP 表面。它不会加密任何静态数据。请参阅安全。

如果你更愿意在你拥有的域名上自行终止 TLS，请将 A 记录指向该机器，并在前面放置 Caddy。添加 compose.override.yaml：

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    ports: ["80:80", "443:443"]
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
volumes:
  caddy_data:

# Caddyfile
mail.example.com {
    reverse_proxy your-mail-mcp:8080
}

开放两个端口——80 不是可选的，Caddy 使用它进行证书质询和 HTTPS 重定向：

sudo ufw allow 80/tcp && sudo ufw allow 443/tcp

Caddy 自行获取并续期证书。将 PUBLIC_URL 设置为主机名，然后执行 docker compose up -d。

账户文件

以只读方式挂载在 /config/accounts.json（参见 compose.yaml）。JSON，使用 encoding/json 解析，在解析前根据进程环境进行展开，因此任何字符串值中的 ${VAR} 都会被替换为同名环境变量。这就是密钥不留在文件中的方式：

{
  "accounts": [
    {
      "name": "work",
      "host": "imap.gmail.com",
      "user": "you@example.com",
      "password": "${WORK_PASS}"
    }
  ]
}

每个账户的键：

账户名称必须唯一。至少需要一个账户；空的 accounts 数组是启动错误。

环境变量

CONFIG、MAILDIR 和 INDEX 是必需的；没有它们进程拒绝启动。PUBLIC_URL 和 OAUTH_PASSPHRASE 是 OAuth 层所必需的，没有它们进程也会启动失败。

容器镜像已经设置了其中四个（Dockerfile）：MAILDIR=/mail、INDEX=/index、CONFIG=/config/accounts.json、LISTEN_ADDR=:8080。compose.yaml 不会覆盖其中任何一个。除非你同时更改 compose.yaml 中相应的卷挂载或配置挂载，否则请保持它们不变——不随之移动挂载点的覆盖会将服务器指向空路径或缺失路径。

不使用 Docker

Linux 和 macOS 的发布二进制文件（amd64 和 arm64）位于发布页面，附带校验和。该二进制文件会调用 mbsync、notmuch 和 w3m，因此请先安装它们——macOS 上使用 brew install isync notmuch w3m，Debian 和 Ubuntu 上使用 apt install isync notmuch w3m。isync 1.4.4 或更新版本可用。

然后使用与容器相同的配置，路径由你选择。容器的卷最初是挂载点，空 maildir 守卫将其视为真正的首次运行；你自己创建的普通目录在该守卫看来与缺失卷完全一样，因此它需要 INIT_MIRROR=1 来表明这里确实是首次运行：

mkdir -p mail index
CONFIG=./accounts.json MAILDIR=./mail INDEX=./index INIT_MIRROR=1 \
PUBLIC_URL=http://127.0.0.1:8080 OAUTH_PASSPHRASE=... \
WORK_PASS=... ./your-mail-mcp

不支持 Windows：maildir 处理依赖 Unix 文件系统语义，而且没有可调用的 mbsync。

自行构建

CI 会构建、测试并发布每个镜像，所以没有人需要这样做——但如果你想，只需一条命令：容器使用 docker build -t your-mail-mcp .，二进制文件使用 go build（Go 1.27，测试需要上述三个工具在 PATH 中）。

提供商说明

iCloud 的说明来自一个早于本服务器的真实 iCloud 镜像的长期运行。Gmail 和 Dovecot 的说明来自提供商文档和项目的研究，尚未全部通过本服务器重新验证。

• iCloud（imap.mail.me.com）：IMAP 的 user 是短名称——即 @icloud.com 之前的部分——而不是完整的电子邮件地址。iCloud 会限制并发 IMAP 连接；这就是生成的 mbsync 配置为每个账户固定 PipelineDepth 1 的原因，且该值不可配置。

• Gmail（imap.gmail.com）：需要应用专用密码（App Password），而这要求账户先启用两步验证——Gmail 不接受直接通过 IMAP 使用账户密码登录。Gmail 还会在 [Gmail]/All Mail 中保留几乎所有内容的副本，因此 Gmail 账户的镜像大小大约是文件夹列表所示的两倍，因为大多数邮件同时存在于其所属文件夹和 All Mail 中。大型 Gmail 账户的首次镜像需要数小时，而且 Google 还强制执行每日 IMAP 下载配额（每天约 2.5GB），因此数 GB 的邮箱会将首次镜像分散到数天完成。这是正常现象：服务器会按自己的计划持续重试，mbsync 会从上次中断处继续。将 SYNC_TIMEOUT 设置为类似 8h 的值以用于首次镜像，这样长时间运行就不会被默认的一小时截止时间截断。

• Dovecot 服务器（许多自托管和小型提供商）通常会在文件夹名称前加上 INBOX. 前缀（例如 INBOX.Sent）。如果 folders 显示了你意料之外的文件夹名称，通常就是这个原因。

安全

账户密码通过进程环境提供（accounts.json 中的 ${VAR}，或字面值）。启动时，服务器会将它们写入容器内磁盘上生成的 mbsync 配置文件中，文件权限为 0600。该文件未加密。任何能够读取容器环境或该文件的内容，都可以以明文读取密码。

静态保护——磁盘加密、限制谁可以 exec 进入容器、对主机的访问——是运维人员的责任。此服务器不声称对凭据进行静态加密，也不尝试这样做。

OAuth 口令以恒定时间检查，并以单一共享密钥控制整个服务器；它不是按用户的凭据系统。请以同样的谨慎态度对待 OAUTH_PASSPHRASE 和邮件账户密码。

search 的线程摘要包含匹配线程中每条消息的显示名称，而该名称由发件人控制。默认排除的文件夹（垃圾邮件、废件箱）中的消息，仍然可以通过这种方式将其自行选择的名称呈现在你面前，即使其正文永远不会出现——search 不会获取或显示被排除消息的正文。thread 和 show 是只读路径，不受此影响：thread 默认排除垃圾邮件/废件箱回复（见上方工具表），而 show 读取你已拥有其 id 的单条消息。search 中的此显示名称泄露问题在本版本中未修复。

故障排查

"maildir ... is an empty plain directory, not a mount point: refusing to sync" —— 服务器会检查你的 maildir 是否为已挂载的文件系统。恰好为空的已挂载卷属于首次运行，无需任何额外操作即可同步，这就是 compose 不需要额外步骤的原因。空的普通目录则存在歧义：全新的 maildir 看起来与卷从未挂载的路径完全一样，而同步到后者会将每个账户重新下载到一个目录中，该目录在你修复挂载的瞬间就会消失。要么将存储挂载到 MAILDIR 指向的位置，要么如果它确实应该是此文件系统上的普通目录，则设置 INIT_MIRROR=1。

"maildir ...: no such file or directory" —— 该路径完全不存在。使用 compose 时，这意味着卷或绑定挂载在 compose.yaml 中缺失；直接运行二进制文件时，则意味着 MAILDIR 有误。

使用 folders 工具检查每个账户的同步状态。 它会列出每个已配置的账户、其上次成功同步时间、上次错误（如有）、其文件夹以及索引中的标签。密码错误或应用专用密码过期的单个账户不会阻止其他账户——同步失败按账户隔离——但它会在此处以 last error 行显示，而不是静默无响应。

垃圾邮件/废件箱排除，两种不同的失败形态：

• 容器日志中出现 "special-use discovery: account NAME: ..." 表示该账户的启动连接、登录或 LIST 完全失败。在此失败情况下，没有文件夹名称可用来进行匹配回退，因此该账户完全不会排除任何内容——甚至不会按内置英文名称列表排除——直到连接问题修复或手动为其设置 exclude_folders。

• 没有错误行，但 folders 仍显示未排除任何内容 表示 LIST 成功——只是服务器未通告 \Junk/\Trash 属性（不支持 RFC 6154 SPECIAL-USE）且其文件夹名称与内置英文列表（junk、spam、trash、deleted messages、deleted items、bulk mail）不匹配。这就是本地化邮箱的情况——例如德语或法语邮箱——解决方法相同：手动设置 exclude_folders。

accounts.json 中的 exclude_folders，例如 "exclude_folders": ["Papierkorb"]，在任何情况下都优先于 SPECIAL-USE 和内置列表。