Gmail MCP Helper

解决在中国大陆等需要代理的环境下，Claude Code 使用 Gmail MCP Server 的认证和连接问题。

为什么需要这个项目？

gmail-mcp-server 是一个优秀的 Gmail MCP 服务器，但在代理环境下存在两个问题：

1. OAuth 认证无法完成 — Node.js 不自动使用系统代理，--setup-auth 命令连接 Google 服务器超时
2. Token 交换失败 — 浏览器授权成功后，回调服务器无法通过代理向 Google 交换 token

本项目提供了代理感知的 OAuth 脚本和邮件操作工具，解决了这些问题。

快速开始

1. 前置条件

• Node.js >= 18
• Claude Code CLI
• Google Cloud Console 项目（已启用 Gmail API）
• 代理（可选，如 127.0.0.1:7890）

2. 获取 Google OAuth 凭证

参考 docs/deployment.md 中的详细步骤。

3. 运行 OAuth 认证

# 设置代理并运行（PowerShell）
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
node gmail-oauth-setup.mjs --client-id "YOUR_CLIENT_ID" --client-secret "YOUR_CLIENT_SECRET"

浏览器打开输出的链接，完成 Gmail 登录授权。

4. 配置 Claude Code

编辑 ~/.claude/mcp.json：

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "gmail-mcp-server@latest",
        "--client-id", "YOUR_CLIENT_ID",
        "--client-secret", "YOUR_CLIENT_SECRET"
      ]
    }
  }
}

5. 安装 Skill（可选）

将 skill/SKILL.md 复制到 ~/.claude/skills/gmail/SKILL.md，即可在任意对话中通过 /gmail 调用邮件操作。

文件说明

gmail-mcp-helper/
├── README.md                    # 项目说明
├── .env.example                 # 凭证模板
├── .gitignore                   # Git 忽略规则
├── gmail-oauth-setup.mjs        # OAuth 认证脚本（代理感知）
├── gmail-fetch.mjs              # 邮件读取脚本
├── gmail-download.mjs           # 附件下载脚本
├── skill/
│   └── SKILL.md                 # Claude Code Gmail Skill
└── docs/
    ├── deployment.md            # 完整部署指南
    └── usage.md                 # 使用指南

核心脚本

gmail-oauth-setup.mjs

OAuth 认证脚本，核心解决代理问题：

• 通过 net.connect() 连接代理
• 使用 HTTP CONNECT 隧道建立 TLS 连接
• 手动构造 HTTP 请求完成 token 交换

gmail-fetch.mjs

邮件读取工具，通过代理读取最新邮件。

gmail-download.mjs

附件下载工具，搜索带附件的邮件并下载到本地。包含健壮的 JSON 解析器，正确处理 Gmail API 返回的大型响应。

常见问题

Q: 认证时报错 access_denied

A: 在 Google Cloud Console 的 OAuth 同意屏幕中添加你的 Gmail 为测试用户。应用保持"测试"模式即可，不需要发布。

Q: connect ETIMEDOUT

A: 代理未生效。确保设置了 HTTP_PROXY 和 HTTPS_PROXY 环境变量。

Q: JSON 解析报错 Incomplete JSON

A: 参见 docs/deployment.md 中的排查记录，使用改进的 JSON 解析器。

Q: Token 过期

A: access_token 1 小时过期，MCP 服务器自动用 refresh_token 刷新。refresh_token 90 天未使用会过期，需要重新运行 gmail-oauth-setup.mjs。

致谢

• gmail-mcp-server — Gmail MCP 服务器
• Model Context Protocol — MCP 协议

License

MIT