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中没有秘密）
- 下载OAuth客户端JSON（谷歌云控制台）并将其存储在本地。
推荐：
- 将其存储在仓库外，或
- 把它放在下面
secrets/（忽略）
- 创建本地配置：
- 复制
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/.
- 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).