Gmail Postmaster Tools

Gmail Postmaster Tools MCP

一个用于 Gmail Postmaster Tools API（v2） 的 MCP 服务，可通过 Claude、Cursor 或任何 MCP 客户端查询您的网域、发件人合规状态和 Gmail 流量指标。

这是一个供发件人亲自使用的自带凭据工具：您提供自己的 Google OAuth 客户端，服务会在本地运行登录流程。所有内容均不会托管，数据也不会离开您的设备。

想要使用它，但不想设置 Google Cloud 项目？这正是 Postmaster+ 的用途——托管式、多服务商 （Gmail + Outlook 等），提供验证、历史记录和告警。

由 OptiPub 的 Postmaster+ 团队构建并维护。

您将获得

• list_domains / get_domain — 已注册的网域及其验证状态
• get_compliance_status — SPF、DKIM、DMARC、对齐、邮件格式、DNS 记录、TLS 加密、用户举报的垃圾邮件率，以及一键退订 / 已执行退订的判定结果
• query_domain_stats — 任意日期范围内的垃圾邮件率、身份验证成功率（SPF/DKIM/DMARC）、TLS 加密率、投递错误和反馈循环指标
• gpt_authenticate / gpt_auth_status / gpt_sign_out

注意：Postmaster Tools v2 涵盖流量指标和合规性。网域和 IP 信誉 不属于 v2 的范围。

前置条件：创建 Google OAuth 客户端（一次性操作，约 5 分钟）

您需要一个 Google Cloud OAuth 客户端，因为 Google 不会为此 API 提供共享的公共客户端。

1. 前往 Google Cloud Console 并创建（或选择）一个项目。
2. APIs & Services → Library → 搜索 “Gmail Postmaster Tools API” → Enable。
3. 打开 APIs & Services → OAuth consent screen（将跳转至 Google Auth Platform）。如果项目从未配置过，请点击 Get started，设置 App name 和支持邮箱、Audience = External，以及联系邮箱。如果已配置，您会看到相应选项卡——跳到下一步即可。
4. 打开 Audience 选项卡。如果 User type = External，请在 Test users → + Add users 下添加您的 Google 地址，然后点击 Save（保持状态为 Testing——无需应用验证即可使用，最多支持 100 位用户）。如果 User type = Internal（Workspace 组织项目），则无需添加测试用户——组织用户可以直接登录。
5. 打开 Clients 选项卡（或 APIs & Services → Credentials）→ Create client → 应用类型选 Desktop app → Create。
6. 复制 Client ID 和 Client secret。

安装时，您需要将这两个值填入此扩展的配置中。（请确保用于登录的 Google 账号有权访问 Gmail Postmaster Tools。）

在 Claude / Cowork 中安装（.mcpb）

.mcpb 仅用于方便地打包 Claude Desktop / Cowork。

1. 从最新版本下载 gmail-postmaster-tools.mcpb。
2. Settings → Capabilities → install extension，选择该文件。
3. 出现提示时，粘贴您的 Google OAuth Client ID 和 Client Secret。
4. 运行一次 gpt_authenticate——浏览器将打开 Google 登录页面。

与其他 MCP 客户端配合使用（Cursor、VS Code、Windsurf 等）

本质上，这是一个标准的 stdio MCP 服务——任何可以运行本地 MCP 服务的客户端都能直接使用它，无需 .mcpb。克隆或下载仓库，然后让客户端指向 server/index.js，并通过环境变量传入 Google 凭据。

Cursor — 编辑 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（每个项目）：

{
  "mcpServers": {
    "gmail-postmaster-tools": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-postmaster-tools-mcp/server/index.js"],
      "env": {
        "GPT_CLIENT_ID": "xxxxx.apps.googleusercontent.com",
        "GPT_CLIENT_SECRET": "xxxxx"
      }
    }
  }
}

VS Code（.vscode/mcp.json）、Windsurf、Claude Desktop（手动配置）以及大多数其他客户端使用相同的 command + args + env 结构——区别仅在于配置文件的位置。其他环境变量覆盖项请参阅配置。

首次调用工具（或调用 gpt_authenticate）时，会打开浏览器进行 Google 登录；127.0.0.1 回环地址适用于任何本地桌面客户端。

**仅支持远程服务的客户端（如 Perplexity、ChatGPT 连接器）：**这些客户端只接受远程 HTTPS MCP 服务 URL，不接受本地命令，因此无法直接添加此 stdio 版本。要使用它，需要托管服务——这正是 Postmaster+ 提供的服务。

使用示例

• “帮我登录 Gmail Postmaster Tools” → gpt_authenticate
• “列出我的 Postmaster 域名” → list_domains
• “example.com 是否符合 Gmail 的发件人规则？” → get_compliance_status { domain: "example.com" }
• “过去 30 天内 example.com 的垃圾邮件率” → query_domain_stats { domain: "example.com", start_date: "...", end_date: "...", metrics: ["SPAM_RATE"] }
• “example.com 的 DKIM 身份验证成功率” → query_domain_stats { domain: "example.com", metrics: [{ "standardMetric": "AUTH_SUCCESS_RATE", "filter": "auth_type=\"dkim\"" }] }

某些指标需要筛选条件：AUTH_SUCCESS_RATE（auth_type=spf|dkim|dmarc）、TLS_ENCRYPTION_RATE（traffic_direction=inbound|outbound）、DELIVERY_ERROR_RATE（可选的 error_type=...）。SPAM_RATE 不需要筛选条件。

身份验证的工作方式

使用 OAuth 2.0 授权码 + PKCE，通过 http://127.0.0.1:<dynamic-port> 回环重定向（这是 Google 为桌面应用推荐的流程）。登录时，服务会在 127.0.0.1 上启动一个短时监听器，打开浏览器，接收授权码，然后使用客户端密钥和 PKCE 验证器交换令牌。

即使是桌面应用，Google 也要求提供客户端密钥，因此这两个值都不可缺少。令牌仅存储在你的设备上，路径为 ~/.gmail-postmaster-mcp/tokens.json（0600），并已加入 git 忽略列表。

**权限范围：**默认情况下，服务会请求 postmaster.traffic.readonly（指标 + 合规性）和 postmaster.domain（列出/获取域名）。如果想缩小权限范围，可通过 GPT_SCOPE 环境变量覆盖（例如，仅保留流量相关权限，舍弃 list_domains/get_domain）。

令牌有效期（重要）

对于发布状态为 Testing 的 OAuth 应用（上述设置步骤为跳过验证而使用的模式），Google 会在 7 天后撤销刷新令牌。实际使用中，你需要大约每周重新运行一次 gpt_authenticate。服务会妥善处理这种情况：刷新失败时，工具调用会提示你重新进行身份验证。

若要停止每周重新进行身份验证，请将 OAuth 应用的发布状态设为 In production（Google Auth Platform → Audience → Publish app）。关于 postmaster（敏感）权限范围的说明：

• Production, unverified — 刷新令牌不再于 7 天后过期。你仍需点击确认，通过“Google 尚未验证此应用”提示页面；在通过验证前，应用的用户数上限为 100。对于个人单用户使用，这是最简单的解决方法。
• Verified — 提交应用以进行 Google OAuth 验证，从而移除警告和用户数上限。只有在广泛分发应用时才值得这样做。

配置（环境变量覆盖）

变量	用途	默认值
GPT_CLIENT_ID	Google OAuth 客户端 ID（必需）	—
GPT_CLIENT_SECRET	Google OAuth 客户端密钥（必需）	—
GPT_SCOPE	以空格分隔的 OAuth 范围	traffic.readonly + domain
GPT_API_BASE	API 基础 URL	https://gmailpostmastertools.googleapis.com/v2
GPT_TOKEN_DIR	令牌缓存目录	~/.gmail-postmaster-mcp
GPT_LOGIN_TIMEOUT_MS	登录等待时间	180000
GPT_REQUEST_TIMEOUT_MS	每次请求的超时时间	60000

构建

npx @anthropic-ai/mcpb validate manifest.json
npx @anthropic-ai/mcpb pack . gmail-postmaster-tools.mcpb

推送 vX.Y.Z 标签会触发 CI 打包，将 .mcpb 附加到 GitHub Release，并发布到 MCP Registry。

为什么零依赖

仅使用 Node.js 内置模块（http、https、crypto、readline）——打包体积小，没有供应链风险，也无需执行 npm install。

贡献

请参阅 CONTRIBUTING.md。

许可证

MIT © OptiPub

---

与 Google 无关联，也未获其认可。“Gmail”、“Google”和“Postmaster Tools”是 Google LLC 的商标。