Gmail Storage & Cleanup MCP

一个专注的本地 MCP 插件，适用于 Codex 和 Claude Code，可监控共享的 Google 存储空间，并通过一套确定性的、审查优先的清理工作流帮助回收 Gmail 空间。

它会检查 Google 存储配额，找出体积较大的 Gmail 清理候选邮件，解释每一项安全决策，并且在将邮件移至回收站之前要求确认。它永远不会永久删除邮件。此仓库中不包含任何凭据。

为什么会有这个项目

对于常规收件箱操作（例如搜索邮件、总结会话、起草回复、转发和添加标签），官方的 Gmail 插件是更好的选择。

这个项目刻意专注于一个不同的问题：在不盲目删除重要邮件的前提下，防止 Google 账号存储空间耗尽。

此对比描述的是每个插件文档化的重点，而非上游连接器未来可能添加的每一项能力。

Related MCP server: Gmail Guardian

安装

要求：Python 3.12+、Git，以及一个已开通 Gmail 的 Google 账号。

git clone https://github.com/ashutoshchaubeypm/Gmail-MCP-tool.git
cd Gmail-MCP-tool
./scripts/setup.sh

1. 创建 Google 凭据

在 Google Cloud Console 中：

1. 创建一个项目，并启用 Gmail API 和 Google Drive API。

2. 配置 Google Auth Platform。对于个人测试，请使用 External/Testing，并将您的 Gmail 地址添加为测试用户。

3. 创建一个应用类型为 Desktop app 的 OAuth 客户端。

4. 打开 .env 并添加生成的值：

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

授权一次：

.venv/bin/python -m app.auth_cli

本地令牌会被写入 work/google-token.json。该文件与 .env 都会被 Git 忽略。

2. 在 Codex 中安装

在仓库根目录下：

codex plugin marketplace add "$PWD"
codex plugin add gmail-mcp-tool@personal

启动一个新的 Codex 任务，然后询问：“检查我的 Google 存储空间，并找出可供审查的 Gmail 清理候选邮件。”

3. 在 Claude Code 中安装

在仓库根目录下：

claude plugin marketplace add "$PWD"
claude plugin install gmail-mcp-tool@gmail-mcp-tool

安装完成后，启动一个新的 Claude Code 会话。

核心工具

• get_storage_quota — 共享 Google 存储空间使用情况

• scan_cleanup_candidates — 只读的 Gmail 发现与确定性评分

• get_candidate_details — 审查最新扫描中的一条结果

• move_message_to_trash — 将一条已确认且不受保护的消息移至回收站

受保护标签包括 STARRED、IMPORTANT、SENT 和 DRAFT。无法明确分类的邮件会保留在待审查状态。消息必须来自最新扫描，之后才能被移动，并且该工具无法对受保护的消息执行操作。此插件不会清空回收站，也不会永久删除消息。

开发

.venv/bin/python scripts/security_check.py
.venv/bin/python -m pytest -q

插件源码：plugins/gmail-mcp-tool/

刻意排除的范围

• 存储预测和定时配额检查

• 更透明的清理策略和规则自定义

• 回收空间的汇总估算和清理报告

• 对不明确的候选进行可选分类，且不会绕过确定性保护

常规的收件箱搜索、邮件摘要、回复起草和转发则有意留给官方的 Gmail 插件。

安全

切勿提交 .env、下载的 OAuth JSON 或 work/google-token.json。在发布更改之前，请运行 python scripts/security_check.py。如果凭据曾被提交，请立即撤销并轮换它们——仅从最新提交中移除是不够的。

采用 MIT 许可。