gmail-mcp-server

这是一个 MCP 服务器，对外公开一个工具 send_email，通过 Gmail API 发送 Gmail 邮件（可附带文件附件）。专为在 Claude Code 中作为本地 stdio MCP 服务器使用而构建。

范围刻意保持狭窄：仅 gmail.send（无邮箱读取/修改权限）——对于一个唯一职责是发送邮件的工具而言，这是最小权限。

这份 README 根据实际首次配置的过程编写，包含过程中出现的每一个错误。按顺序从头到尾操作，你应该不会碰到其中任何一个。

PowerShell 注意： && 在 Windows PowerShell 中不能用作命令分隔符（那是 bash/cmd 的语法）。下面的每一条多命令行都写成独立行，如果想写成一行，请使用 ;： cd C:\Users\GaneshGupta\gmail-mcp-server; python auth_setup.py

1. Google Cloud — 启用 API 并创建 OAuth 凭据

Google 的控制台界面最近已将“OAuth consent screen”更名为 Google Auth Platform，设置分布在左侧导航的不同页面中（Branding / Audience / Clients / Data Access / Verification Center）。以下步骤使用当前名称。

1. 打开 console.cloud.google.com。创建新项目或复用现有项目。

2. APIs & Services → Library → 搜索“Gmail API” → Enable。

3. APIs & Services → OAuth consent screen（这会进入新的 Google Auth Platform 部分）→ 填写 Branding 页面：

   • App name：任意内容，例如 gmail-mcp-tool

   • User support email：你的 Gmail 地址

   • Developer contact email：你的 Gmail 地址

   • 暂时将 logo/App domain 字段留空 —— 如果遇到“incomplete configuration”错误，第 4 步再回来填写 App domain。 不要预先猜测填写；只有确实看到该错误时才填写。

4. Audience 页面（左侧导航）→ 在 Test users 下 → + Add users → 输入你自己的 Gmail 地址（将用于发送邮件的那个）→ Save。

   如果“Add users”被黄色横幅拦截，提示 “Your app's OAuth configuration is incomplete... Please visit the Branding page” —— 这是因为 gmail.send 是敏感范围（sensitive scope），即使对于仅处于 Testing 状态的应用，也要求 App domain 字段非空。解决方法：

   • 进入 Branding → App domain，填写：

     • Application home page：https://example.com

     • Application privacy policy link：https://example.com/privacy

     • Application terms of service link：https://example.com/terms

   • 这将显示出一个 Authorized domains 字段。只输入裸域名——不要加 https:// 前缀：

     • 正确：example.com

     • 错误（会提示“Invalid domain: must not specify the scheme”）：https://example.com

   • 在 Branding 页面保存（你应该会看到“Branding changes saved!”通知）。

   • 回到 Audience → Add users 再试一次 —— 这次会成功。

   这些 URL 不需要真实/可用 —— 只要应用仍处于 Testing 状态，Google 就不会验证它们，只是要求字段已填写。

5. Clients 页面（左侧导航）→ + Create client：

   • Application type：Desktop app

   • Name：任意内容，例如 gmail-mcp-desktop

   • Create → Download JSON（创建后立即出现该按钮）

6. 下载的文件名类似 client_secret_<long-id>.apps.googleusercontent.com.json。将其完全重命名为 client_secret.json，并移动到：

   C:\Users\GaneshGupta\gmail-mcp-server\credentials\client_secret.json

   确切的文件名很重要 —— gmail_auth.py 会按该名称查找，如果名称不匹配，会抛出 FileNotFoundError（这是这里最容易出错的地方）。

Related MCP server: Gmail MCP Server

2. 安装依赖

cd C:\Users\GaneshGupta\gmail-mcp-server
pip install -r requirements.txt

3. 一次性登录

python auth_setup.py

流程如下：

1. 浏览器窗口会打开一个正常的 Google 登录页面。

2. 你会看到 “Google hasn't verified this app”。这是预期情况 —— 这是你自己的 OAuth 客户端，处于 Testing 模式，正在请求敏感范围。点击 Continue（旧版界面：Advanced → Go to [app name] (unsafe)）。

3. 授予“Send email on your behalf”权限。

4. 浏览器显示 “The authentication flow has completed. You may close this window.”

5. 终端会输出 Authorized. Token saved to ...credentials\token.json。

如果第 2 步反而显示 Error 403: access_denied / “has not completed the Google verification process... can only be accessed by developer-approved testers” —— 说明你的 Gmail 地址还没有加入 Audience → Test users 列表。请回到上面的步骤 1.4。

只需执行一次。之后，server.py 只会静默刷新已保存的 token，绝不再自行打开浏览器。

4. 检查 token 是否正常（可选但推荐）

python -c "from gmail_auth import load_credentials; c = load_credentials(); print('valid:', c.valid); print('scopes:', c.scopes); print('has refresh token:', bool(c.refresh_token))"

期望看到 valid: True、scopes: ['https://www.googleapis.com/auth/gmail.send']、has refresh token: True。

5. 注册到 Claude Code

claude mcp add gmail-sender --scope user -- python C:\Users\GaneshGupta\gmail-mcp-server\server.py

--scope user 会全局注册 —— 从那时起，它在这台机器的每个 Claude Code 会话中都可用，而不只是你运行命令的那个会话。它不会追溯出现在已运行的会话中 —— MCP 服务器在会话启动时加载，因此要使用新的终端 / 新的 claude 会话才能看到它。

验证：

claude mcp list

你应该在列表中看到 gmail-sender。

6. 使用

在任意 Claude Code 会话中（完成上述注册后），直接用自然语言提出需求即可：

向 jane@example.com 发送一封邮件，主题为“跟进”，正文为“...”，并附上 C:\path\to\file.pdf

Claude Code 会直接调用 send_email 工具。每个会话无需额外配置。

工具参考

send_email(to, subject, body, attachments=None, cc=None, bcc=None, html=False)

• to / cc / bcc：逗号分隔的地址

• attachments：绝对本地文件路径列表，合计限制 15MB（Gmail 的原始发送上限为 25MB；15MB 原始文件为 base64 膨胀 + 邮件头留出了余量）

• html：设为 true 则发送 HTML 正文，而不是纯文本

• 返回 {status, message_id, thread_id, to, subject, attachment_count}

故障排查索引

注意事项

• credentials/client_secret.json 和 credentials/token.json 已被 gitignore —— 切勿提交它们。

• 要从不同的 Gmail 账户发送，请删除 credentials/token.json 并重新运行 auth_setup.py。