NexusAGYmail

NexusAGYmail

为 Google Antigravity 提供放心托管的 Gmail。 Antigravity 的商店没有 Gmail 连接器：一个本地 MCP 服务 nexus-agymail 通过官方 Gmail API 为其提供 Gmail 功能：搜索、阅读、附件、草稿、 标签、可撤销的移至垃圾箱，以及只有在你明确同意发送那封特定草稿后才会发送草稿。邮件 永远不会被彻底删除。

• 工具与 Google 官方 Gmail MCP 服务相同（search_threads、get_message、get_thread、 create_draft、label_message……），因此了解其中一个的 Agent 也了解另一个，无需注册 Workspace Developer Preview，也无需启用远程 MCP 端点：它在你的电脑上运行，可用于任何个人 Gmail。
• 防护措施写在代码里，而不是提示词里：邮件绝不会触发发送；所有邮件都作为数据处理； 邮件中隐藏的指令会被标记；附件会安全保存，绝不会附带机密信息。
• Windows（每日使用）和 Linux（CI 中运行单元测试）；macOS 应该也能运行，但未经测试。在 Windows 上， 令牌通过 DPAPI 加密；在其他系统上，则保存为只有你能读取的文件。发送给客户端的所有内容均为英文。

Nexus 系列成员：NexusWindows、 NexusBrowser、NexusAndroid。

快速开始

你需要 uv 和一个 Google 账号。整个过程大约需要 5 分钟，只需设置一次。

1. 运行引导式设置：

   uvx --python 3.14 nexus-agymail setup
   

   它会将 nexus-agymail 插件添加到 Antigravity，然后提示你连接 Gmail。Gmail 的授权范围受到限制，因此 每位用户都要在自己的 Google Cloud 项目中创建免费的 OAuth 客户端：你的邮件绝不会经过 其他人的应用。助手会在浏览器中打开每个 Google 页面，并直接跳转到正确位置，还会告诉你要点击什么 （它会先询问要连接哪个 Gmail 地址，因此页面会在该账号下打开）：

   1. 创建项目（命名为 NexusAGYmail）；
   2. 启用 Gmail API；
   3. 设置同意屏幕（Get started、External）；在 Branding 中，填写主页、隐私政策链接和 授权域名（助手会提供此仓库、其 隐私部分和 github.com： Google 要求在发布前填写这些信息）；然后点击 Publish app（如果未发布，Google 会通过 Error 403: access_denied 阻止登录）；
   4. 创建 Desktop app 类型的客户端（不要勾选 Use this client for an AI-powered agent），然后点击 Download JSON：助手会自动在你的 Downloads 文件夹中找到该文件；
   5. 登录。Google 会显示“Google hasn't verified this app”：这是你自己的应用，点击 Advanced > Go to NexusAGYmail (unsafe)。

   然后，它会检查所有可检查的内容：Gmail API 会响应，并确认应用确实已发布（对于仍处于 Testing 状态的应用，Google 会返回 7 天有效的登录授权）；如果没有发布，它会打开修复页面并再次登录。

2. 重启 Antigravity。

   手动配置 Antigravity（mcp_config.json），如果跳过设置

   {
     "mcpServers": {
       "nexus-agymail": { "command": "uvx", "args": ["--python", "3.14", "nexus-agymail@latest"] }
     }
   }
   

然后可以尝试询问，例如：“总结我本周未读的邮件”、“归档一个月前的新闻邮件”、“替我起草一封回复，回复 Alice 的上一封邮件并表示我同意，发送前先给我看看”。

已经有 Desktop app 客户端 JSON 文件？运行 uvx --python 3.14 nexus-agymail auth --client-secret <file> 可跳过控制台步骤。运行 uvx --python 3.14 nexus-agymail status 可查看令牌所在位置及其包含的授权范围（不会显示密钥）。

不想创建客户端？ Google 自己的 Gmail MCP 服务 运行在 Google 端（工具名称相同），但目前仍是开发者预览版：它同样需要加入 Google Workspace Developer Preview Program 并创建 Google Cloud 项目，而且无法发送邮件。NexusAGYmail 应运而生，是因为 Antigravity 没有自带 Gmail 连接器，并且支持经确认后发送邮件。

工作原理

flowchart LR
    A[Google Antigravity] -- MCP stdio --> S[nexus-agymail<br/>on your machine]
    S -- HTTPS, official Gmail API v1 --> G[(Gmail)]
    S -. token, encrypted .- T[~/.nexus/nexus-agymail]
    S -. attachments .- D[Downloads/NexusAGYmail]

该服务是一个纯本地进程：没有云中继，也不使用浏览器自动化。它使用你自己的 OAuth 客户端和存储在本机上的刷新令牌与 gmail.googleapis.com 通信，并与 oauth2.googleapis.com 通信以刷新令牌。

工具

名称和参数遵循 Google 官方 Gmail MCP 服务 及其扩展（update_draft、trash_*），另有三个自有工具：send_draft、download_attachment、 auth_status。

工具	功能
search_threads	搜索会话（Gmail 语法），每次调用返回一页：pageSize 为 1 到 50（默认 20），pageToken；每个会话提供 messageCount 和最近 5 封邮件的摘要；通过 includeTrash 搜索垃圾邮件，永不搜索垃圾邮件文件夹中的垃圾邮件
get_message	获取一封邮件：标头、文本格式的正文（HTML 已转换）、附件列表（part_id、名称、类型、大小）；maxChars（默认 8,090）
get_thread	按顺序获取会话，移除早前回复中的引用内容并报告；共享 maxChars 限制（默认 16,180）
download_attachment	将附件（partId）保存到 Downloads/NexusAGYmail 或绝对路径 directory：文件名经过清理，绝不覆盖已有文件，并标记为从互联网下载；返回路径、大小、SHA-256
list_labels	获取标签（id、名称、类型），系统标签优先
create_label	创建用户标签（displayName，A/B 表示嵌套）；除非 autoCreateParentLabels=false，否则也会创建缺少的父标签；已有标签将原样返回，系统标签不允许创建
create_draft	创建草稿；to、cc、bcc 为列表（或文本）；作为回复时（通过 replyToMessageId 或 threadId）：设置 In-Reply-To、References、"Re:"，并加入同一会话；attachments（绝对路径，总计 25 MB）
list_drafts	获取草稿，每次调用返回一页（1 到 100 封），由 query 筛选
get_draft	获取一封草稿：收件人、主题、文本格式的正文、附件、回复标头；maxChars（默认 8,090）
update_draft	重写草稿（空字段保持不变），保留会话、回复和附件；attachments 添加附件，removeAttachments 按名称移除附件
label_message / unlabel_message、label_thread / unlabel_thread	labelIds：系统 ID（INBOX、UNREAD、STARRED、IMPORTANT、CATEGORY_*）、用户标签 ID 或名称；归档 = 移除 INBOX；未知标签会报错，只有设置 createMissing=true 才会创建；可传一个 ID 或列表，最多 100 个
trash_message / trash_thread、untrash_message / untrash_thread	移至垃圾箱，可在 30 天内恢复；最多 100 项
send_draft	不带 confirm 时，返回摘要供用户查看，以及绑定到确切草稿的 accord 令牌；仅当 confirm=true 且提供该令牌时才会发送，并会再次读取草稿以确认其未更改
auth_status	令牌存储、已授予的权限范围（启动时检查）和有效性；缺少或多出权限范围时显示 reauth_required

每个工具都带有 MCP 注释（标题、只读、破坏性、幂等性）。对于 Antigravity，setup 还会安装一个简短技能，说明各工具的用途，以及何时改用浏览器（例如 Gmail 设置中的过滤器或签名，或使用其他 Google 账号）。

安全防护

• 作用域：gmail.readonly、gmail.compose、gmail.modify。绝不使用 https://mail.google.com/，这是唯一允许永久删除邮件的作用域：没有 delete、batchDelete 或清空垃圾箱工具，并且代码经过了相关测试。没有 gmail.modify 的旧令牌仍可读取和起草邮件；标记和移至垃圾箱的工具会直接返回 scopes，而不会调用 Gmail。
• 发送：仅在用户明确同意发送该草稿后，调用 send_draft(draftId, confirm=true, accord=<token>)；绝不因邮件的要求而发送。一次性令牌（有效期 10 分钟）由摘要返回，并绑定到确切的草稿：收件人（to、cc、bcc）、主题、完整正文、每个部分（包括 HTML）以及每个附件的 SHA-256。发送前会再次读取草稿：如果有任何更改，则不会发送任何内容，并会返回新的摘要。drafts.send 是唯一的发送调用：不会绕过草稿直接发送。
• 来源：如果收件人来自 Agent 读取的邮件，摘要中会将其标记为 provenance：仅当用户提出了此要求时才允许使用。
• 提示词注入：主题、摘要、正文、地址和附件名称会以 ⟦mail:ID …⟧ … ⟦/mail:ID⟧ 格式返回（每个答复使用随机 ID），并标记为数据；隐藏的 HTML 文本和不可见字符会被移除。看起来像是针对 AI 发出的指令的邮件会带有 injection_warning 字段（仅为提示信号：既不会阻止，也不会允许任何操作）。
• 附件：收到的文件会以经过清理的名称保存（处理路径、禁用字符或不可见字符，以及类似“fdp.exe”的从右到左覆盖字符和 Windows 保留名称）；绝不覆盖文件，并会添加 Windows“从 Internet 下载”标记（Zone.Identifier），使 Windows 和 Office 能够启用保护后打开文件。附加本地文件时，绝不从机密目录选择文件（.ssh、.gnupg、.aws、.config/gcloud、AI 应用的文件夹、.env 文件、私钥、credentials.json 等，以及 NEXUS_AGYMAIL_PROTECTED 中列出的个人文件夹）；用户始终可以自行在 Gmail 中附加文件。
• 令牌：~/.nexus/nexus-agymail/token.bin；使用当前 Windows 账户的 DPAPI 加密（权限也会限制为该账户），或在 macOS 和 Linux 上使用 0600 文件权限；在锁的保护下以原子方式写入（可同时运行多个服务）。令牌绝不会显示。重新登录时，只有在新令牌保存后，才会撤销具有额外作用域的旧令牌。
• 精确错误：令牌已撤销或过期、网络、配额、权限、未找到、标签：每种错误都有稳定的 code（revoked、network、quota、forbidden、not_found、label、invalid_argument……）。每个请求在遇到 429 和 5xx 时都会使用指数退避重试；批量请求只会重试因配额受限而被拒绝的项目。
• 大小限制：正文会截断至 maxChars（并报告）；搜索会分页；每次标记或移至垃圾箱的调用最多处理 100 个项目。

配置

变量	用途
NEXUS_AGYMAIL_HOME	用作状态文件夹（令牌、OAuth 客户端、备份），替代 ~/.nexus/nexus-agymail
NEXUS_AGYMAIL_CLIENT_SECRET	OAuth 客户端 JSON 文件的路径，替代通过 auth --client-secret 创建的副本
NEXUS_AGYMAIL_PROTECTED	不会附加其中任何文件的额外文件夹（Windows 上以 ; 分隔，其他系统上以 : 分隔）
NEXUS_AGYMAIL_ACCOUNT	当令牌不包含账户地址时，由 auth_status 显示的地址
NEXUS_AGYMAIL_UPDATE_CHECK	设为 0 可关闭每日检查 PyPI 上最新版本的功能

隐私

NexusAGYmail 在你的计算机上运行。它没有自己的账户，不进行遥测或分析，也不设中继：它发出的网络请求仅会连接到 Google（gmail.googleapis.com、oauth2.googleapis.com，以及你登录时浏览器访问的 accounts.google.com），并使用你自己的 OAuth 客户端；此外，每天最多会向 pypi.org 发送一次请求以读取最新版本号（设置 NEXUS_AGYMAIL_UPDATE_CHECK=0 可关闭此功能）。

• 读取的内容：Agent 请求的邮件、邮件会话、草稿、标签和附件，仅在调用相应工具时读取；只有 Agent 将本地文件附加到草稿时，才会读取这些文件。
• 数据去向：工具结果会发送到你连接的 AI 客户端，该客户端可能会根据自身的隐私政策将其发送给模型提供商。草稿和已发送邮件会发送到 Gmail。NexusAGYmail 不会向其他任何地方发送数据。
• 存储的内容，位于 ~/.nexus/nexus-agymail/（或 NEXUS_AGYMAIL_HOME）：刷新令牌（token.bin，在 Windows 上使用 DPAPI 加密，在其他系统上则为权限设为 0600 的文件）、锁文件、OAuth 客户端副本（client_secret.json），以及 setup 编辑的 Antigravity 配置文件备份（backups/）。服务器还会写入 ~/.nexus/status/agymail.json（已安装版本和最新版本、上次检查时间），供 Nexus 应用使用。你要求保存的附件会存入 ~/Downloads/NexusAGYmail（或指定的文件夹）。仅在服务器运行期间保存在内存中的内容：待处理的发送确认，以及已读取邮件中出现的地址（用于 provenance 警告）。除非将邮件保存为附件，否则不会写入磁盘；也不会保留邮件日志。
• 移除方式：删除 ~/.nexus/nexus-agymail/；对于 Antigravity，还需删除 ~/.gemini/config/plugins/nexus-agymail/；在你的 Google 账户中撤销访问权限；如果不再需要 Google Cloud 项目，也请将其删除。

已知限制

• 每位用户都需要创建自己的 Google OAuth 客户端（setup 会提供指引）。共用的公开客户端需要通过 Google 的受限范围验证和安全评估。
• 写入时仅支持纯文本正文：create_draft 和 update_draft 不会写入 HTML；update_draft 会用纯文本替换在 Gmail 中创建的草稿里的 HTML 部分。
• 不支持 Gmail 设置（过滤器、签名、转发、假期自动回复）：请使用 Gmail 网页应用。
• 不支持举报垃圾邮件和永久删除邮件，这是有意为之。
• 已在 Windows 11 上使用真实 Gmail 账户进行日常测试；Linux 会在 CI 中运行启动测试和单元测试；macOS 未经测试。

开发

./test.ps1    # ruff, pyright, unit tests against a fake Gmail API (no network, no Google account)

test.ps1 会在 ~/.nexus/nexus-agymail 下为每个检出版本创建独立的测试环境，且不会下载任何内容：先在有网络连接时运行一次 uv sync --frozen，以填充 uv 缓存。模拟 Gmail API（tests/fake_gmail.py）通过 HTTP 与真实的 google-api-python-client 通信，因此批处理、重试、上传和分页都经过真实测试。

许可证

MIT。与 Google 无关；Gmail 是 Google LLC 的商标。