Gmail Cleanup MCP

gmail清理mcp

用于安全清理Gmail的本地MCP（模型上下文协议）服务器：

• 预览将删除的内容（每个发件人/查询的样本）
• 尝试取消订阅（HTTP一键/GET+ mailto:)
• 将匹配的邮件移至回收站（可恢复）

该项目旨在从支持MCP的客户端（例如OpenCode）使用。

它的作用

MCP stdio上公开的工具：

• preview_cleanup

- 输入：发件人/查询列表（文件或内联文本） - 输出：每个条目的匹配估计（通常有上限/饱和）、一个小样本和发现的取消订阅提示 - 返回a planId 和 confirmPhrase

• execute_cleanup

- 要求：精确 planId + confirmPhrase - 对于每个条目：首先尝试取消订阅，然后将匹配的邮件移动到Gmail垃圾箱 - 输出：垃圾计数+取消订阅统计数据（HTTP与mailto）+a manualRequired 自动化不明确时排队

v1中没有永久删除。

安全模型

• 两步流程： preview_cleanup -> execute_cleanup （需要确认短语）
• 默认查询后缀不包括垃圾邮件和垃圾(-in:spam -in:trash)
• 上限和批处理（全局+每个条目）
• 发件人列表路径allowlist（防止读取任意文件）
• 秘密存在于git之外（通常在 secrets/，这是不可忽视的）

需求

• Node.js>=20
• 启用Gmail API的谷歌云项目
• OAuth桌面客户端凭据

安装

git clone 
cd gmail-cleanup-mcp
npm install
npm run build

配置（Git中没有秘密）

1. 下载OAuth客户端JSON（谷歌云控制台）并将其存储在本地。

推荐：

• 将其存储在仓库外，或
• 把它放在下面 secrets/ （忽略）

1. 创建本地配置：

• 复制 config/config.example.yaml 保存到本地配置文件（建议在存储库之外）。

- 如果你将其保存在repo中，请使用 config/config.yaml （忽略了）。

• 编辑配置文件并为以下对象设置绝对路径：

- oauth.client_file_path - oauth.token_file_path - paths.allowed_list_roots

您可以将配置存储在任何位置，并使用以下任一方式指向它：

• CLI参数： --config /absolute/path/to/config.yaml
• ENV 是 ： GMAIL_CLEANUP_MCP_CONFIG_PATH=/absolute/path/to/config.yaml

重要提示：

• config/*.yaml 故意忽视（除非 config/config.example.yaml).
• 永不承诺 secrets/.

1. Bootstrap OAuth令牌：

npm run auth:bootstrap -- --config /absolute/path/to/config.yaml

或者：

GMAIL_CLEANUP_MCP_CONFIG_PATH=/absolute/path/to/config.yaml npm run auth:bootstrap

这将打印一个授权URL。授权后，令牌将写入中配置的路径 oauth.token_file_path.

如果更改范围，请删除令牌文件并重新运行引导程序。

发件人列表格式

纯文本文件，每行一个条目。空白行和 # 评论被忽略。

接受的线路形式：

• user@example.com -> from:user@example.com
• @example.com 或 example.com -> from:example.com
• 原始Gmail查询（以开头 from: / subject: / has: /等等）

示例：

# emails
newsletter@example.com

# domain
@example.org

# raw Gmail query
from:"Sender Name" older_than:2y
subject:"sale" older_than:1y

看 lists/senders.example.txt.

取消订阅自动化笔记

List-Unsubscribe 支持多种方案，但并非所有方案都能完全自动化。

• HTTP一键(List-Unsubscribe-Post: List-Unsubscribe=One-Click)：通过POST尝试（GET回退）
• HTTP GET链接：已尝试，但通常仍需要手动确认/选项；这些通过以下方式浮出水面 manualRequired
• mailto: 链接：使用Gmail API发送(gmail.send 所需范围）

邮寄安全说明：

• 邮件发送有上限。
• 可以对邮件收件人域进行DNS验证，以减少退回消息。
• 如果条目的HTTP取消订阅已成功，则可以跳过邮件发送。

即使有自动化，一些出版商也会使用偏好中心或确认步骤。

OpenCode（MCP）配置

将本地MCP服务器添加到您的OpenCode配置中（示例）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gmail_cleanup": {
      "type": "local",
      "command": ["node", "dist/index.js", "--config", "/absolute/path/to/config.yaml"],
      "enabled": true,
      "environment": {}
    }
  }
}

确保MCP服务器在repo根目录下使用cwd运行，以便 dist/index.js 存在。

持续集成

CI运行 npm ci, npm run test，以及 npm run build.

安全发布到GitHub

在您按下之前：

• 确认 secrets/ 没有被跟踪，也没有上演。
• 确认没有跟踪本地配置文件（例如。 config/config.yaml).

建议检查：

git status
git check-ignore -v secrets/ config/config.yaml || true

许可证

麻省理工学院（见 LICENSE).