gmail-skill

Gmail 技能 - 邮件和联系人访问

读取、搜索和发送 Gmail 邮件。访问 Google 联系人。

重要：发送邮件前必须获得确认

发送任何邮件前，必须先获得用户的明确确认。

当用户要求发送邮件时：

1. 首先，向用户展示完整的邮件详情：
   • 发件人（使用哪个账户）
   • 收件人
   • CC/BCC（如有）
   • 主题
   • 正文全文
2. 询问：“您要我发送这封邮件吗？”
3. 只有在用户明确确认后（例如“是”“发送吧”“继续”），才能运行发送命令
4. 即使用户一开始就要求发送，也绝不能在未获得确认的情况下发送邮件

以下情况同样适用：

• 用户说“给 X 发封邮件”
• 你处于“危险地跳过权限”模式
• 用户看起来很着急

务必先确认。没有例外。

首次设置（一次性，约 2 分钟）

首次运行时，脚本会引导你完成设置。你需要创建一次 Google Cloud OAuth 客户端：

1. 前往 Google Cloud Console
2. 创建项目（或选择现有项目）
3. 启用 Gmail API 和 People API（APIs & Services → Library）
4. 配置 OAuth 同意屏幕：
   • 用户类型：External
   • 应用名称：Gmail Skill
   • 将自己添加为测试用户
   • 添加以下范围：gmail.readonly、gmail.send、gmail.modify、contacts.readonly
5. 创建 OAuth 客户端 ID：
   • 应用类型：桌面应用
   • 下载 JSON → 保存为 ~/.claude/skills/gmail-skill/credentials.json

然后运行任意命令即可——浏览器会打开，你批准后就完成了。适用于你的所有账户。

**注意：**如果你之前使用过 gmail-reader，需要重新进行身份验证，以授予新的 gmail.send 范围。

命令

搜索邮件

python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "query" [--max-results N] [--account EMAIL]

查询示例：

• from:[email protected] - 来自特定发件人
• subject:meeting after:2026/01/01 - 主题和日期
• has:attachment filename:pdf - 带有 PDF 附件
• is:unread - 未读邮件
• "exact phrase" - 精确匹配

阅读邮件

python3 ~/.claude/skills/gmail-skill/gmail_skill.py read EMAIL_ID [--account EMAIL]

列出最近的邮件

python3 ~/.claude/skills/gmail-skill/gmail_skill.py list [--max-results N] [--label LABEL] [--account EMAIL]

发送邮件（需要确认）

python3 ~/.claude/skills/gmail-skill/gmail_skill.py send --to EMAIL --subject "Subject" --body "Body text" [--cc EMAIL] [--bcc EMAIL] [--account EMAIL]

必需参数：

• --to / -t - 收件人邮箱地址
• --subject / -s - 邮件主题
• --body / -b - 邮件正文

可选参数：

• --cc - CC 收件人（逗号分隔）
• --bcc - BCC 收件人（逗号分隔）
• --account / -a - 指定发件账户

示例：

python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "[email protected]" \
  --subject "Meeting Tomorrow" \
  --body "Hi, just confirming our meeting at 2pm tomorrow." \
  --account [email protected]

标记为已读

python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read EMAIL_ID [--account EMAIL]

标记为未读

python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-unread EMAIL_ID [--account EMAIL]

标记为已读和标记为未读都支持多个 ID（逗号分隔）：

python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read "id1,id2,id3" --account [email protected]

标记为已完成（归档）

将邮件移出收件箱以进行归档。相当于 Gmail 的“e”键盘快捷键。

python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-done EMAIL_ID [--account EMAIL]

取消归档

将邮件移回收件箱（撤销归档）。

python3 ~/.claude/skills/gmail-skill/gmail_skill.py unarchive EMAIL_ID [--account EMAIL]

加星标 / 取消星标

python3 ~/.claude/skills/gmail-skill/gmail_skill.py star EMAIL_ID [--account EMAIL]
python3 ~/.claude/skills/gmail-skill/gmail_skill.py unstar EMAIL_ID [--account EMAIL]

所有标签命令都支持多个 ID（逗号分隔）：

python3 ~/.claude/skills/gmail-skill/gmail_skill.py star "id1,id2,id3" --account [email protected]

邮件格式（兼容 Superhuman）

send 和 draft 会构建 multipart/alternative 邮件（纯文本 + 简单 HTML 段落，不会强制换行，邮件头采用规范大小写）。以这种方式创建的草稿可在 Superhuman 中正常显示和编辑，包括线程回复和附件（已于 2026-10-08 使用三封金丝雀草稿测试）。

send 和 draft 均支持以下额外选项：

• --body-file PATH：从文件读取正文（避免长邮件的 shell 引号问题）
• --attach PATH：附加文件（可重复使用）
• --reply-to-id MESSAGE_ID：将邮件作为回复加入线程（设置 In-Reply-To/References 和 threadId）。send 和 draft 均可使用。

推荐的外联流程：在正确的账户和线程中创建草稿，由用户在 Superhuman 中审核并发送；只有在获得针对该邮件的明确确认后，才使用 send。

创建草稿

创建电子邮件草稿。回复现有电子邮件时，使用 --reply-to-id，以确保 Superhuman 等电子邮件客户端中的邮件正确串联。

python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft --to EMAIL --subject "Subject" --body "Body text" [--reply-to-id EMAIL_ID] [--cc EMAIL] [--bcc EMAIL] [--account EMAIL]

必需参数：

• --to / -t - 收件人电子邮件地址
• --subject / -s - 电子邮件主题
• --body / -b - 电子邮件正文

可选参数：

• --reply-to-id / -r - 要回复的邮件 ID（添加正确的 In-Reply-To 和 References 标头，以便串联邮件）
• --cc - 抄送收件人（以逗号分隔）
• --bcc - 密送收件人（以逗号分隔）
• --account / -a - 在指定账户中创建草稿

示例（新邮件）：

python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "[email protected]" \
  --subject "Draft for Review" \
  --body "Here's my draft message."

示例（回复现有邮件）：

python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "[email protected]" \
  --subject "Re: Original Subject" \
  --body "Thanks for your email..." \
  --reply-to-id 19b99b3127793843 \
  --account [email protected]

列出标签

python3 ~/.claude/skills/gmail-skill/gmail_skill.py labels [--account EMAIL]

列出联系人

python3 ~/.claude/skills/gmail-skill/gmail_skill.py contacts [--max-results N] [--account EMAIL]

搜索联系人

python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "query" [--account EMAIL]

管理账户

# List all authenticated accounts
python3 ~/.claude/skills/gmail-skill/gmail_skill.py accounts

# Remove an account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py logout --account [email protected]

多账户支持

使用新的电子邮件地址和 --account 添加账户——浏览器会为该账户打开：

# First account (auto-authenticates)
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list

# Add work account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account [email protected]

# Add personal account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account [email protected]

# Use specific account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "from:boss" --account [email protected]

令牌按账户存储在 ~/.claude/skills/gmail-skill/tokens/ 中

示例

查找本周的未读邮件

python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "is:unread after:2026/01/01"

阅读特定邮件

python3 ~/.claude/skills/gmail-skill/gmail_skill.py read 18d5a3b2c1f4e5d6

快速发送电子邮件

python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "[email protected]" \
  --subject "Hello!" \
  --body "Just wanted to say hi."

查找某人的联系信息

python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "John Smith"

在个人电脑上查看工作邮箱

python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account [email protected] --max-results 5

输出

所有命令均输出 JSON，便于解析。

要求

• Python 3.9+
• pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client requests

安全说明

• 必须确认后才能发送 - Claude 在发送电子邮件前，必须始终向用户确认
• 令牌存储在本地的 ~/.claude/skills/gmail-skill/tokens/ 中
• 可随时撤销访问权限：https://myaccount.google.com/permissions
• 处于“testing”模式的应用可能每 7 天需要重新授权一次（发布应用即可避免此情况）