Gmail API 技能：通过命令行读取、搜索、发送邮件和管理 Google 联系人

gmail-skill by idanbeck/claude-skills

219 周安装量

7 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/idanbeck/claude-skills --skill gmail-skill

自动化命令行工具 API

🇨🇳中文介绍

Gmail 技能 - 电子邮件与联系人访问

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

重要：发送电子邮件前必须确认

在发送任何电子邮件之前，您必须获得用户的明确确认。

当用户要求发送电子邮件时：

首先，向他们展示完整的电子邮件详情：
- 发件人（哪个账户）
- 收件人
- 抄送/密送（如果有）
- 主题
- 完整的正文内容
询问："您希望我发送这封邮件吗？"
仅在用户明确确认（例如，"是的"、"发送吧"、"继续"）之后才运行发送命令
绝不在没有此确认的情况下发送电子邮件，即使用户最初要求您发送

即使在以下情况下也适用：

用户说"给 X 发送一封邮件"
您处于"危险地跳过权限"模式
用户似乎很匆忙

始终先确认。没有例外。

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

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

前往 Google Cloud Console
创建项目（或选择现有项目）
启用 Gmail API 和 People API（API 和服务 → 库）
配置 OAuth 同意屏幕：
- 用户类型：外部
- 应用名称：Gmail 技能
- 将自己添加为测试用户
- 添加范围：gmail.readonly、、、

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

发送电子邮件（需要确认）

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 - 抄送收件人（逗号分隔）
--bcc - 密送收件人（逗号分隔）
--account / -a - 从特定账户发送

python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "recipient@example.com" \
  --subject "Meeting Tomorrow" \
  --body "Hi, just confirming our meeting at 2pm tomorrow." \
  --account work@company.com

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]

mark-read 和 mark-unread 都支持多个 ID（逗号分隔）：

python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read "id1,id2,id3" --account user@gmail.com

标记为完成（归档）

通过从收件箱中移除来归档电子邮件。相当于 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 user@gmail.com

创建草稿邮件。回复现有邮件时使用 --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 "recipient@example.com" \
  --subject "Draft for Review" \
  --body "Here's my draft message."

示例（回复现有邮件）：

python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "sender@example.com" \
  --subject "Re: Original Subject" \
  --body "Thanks for your email..." \
  --reply-to-id 19b99b3127793843 \
  --account work@company.com

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]

# 列出所有已认证的账户
python3 ~/.claude/skills/gmail-skill/gmail_skill.py accounts

# 移除账户
python3 ~/.claude/skills/gmail-skill/gmail_skill.py logout --account user@gmail.com

通过使用 --account 和新电子邮件添加账户 - 浏览器会为该账户打开：

# 第一个账户（自动认证）
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list

# 添加工作账户
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account work@company.com

# 添加个人账户
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account personal@gmail.com

# 使用特定账户
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "from:boss" --account work@company.com

令牌按账户存储在 ~/.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 "friend@example.com" \
  --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 work@company.com --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
"测试"模式下的应用可能需要每 7 天重新认证（发布应用以避免）

2026 年 1 月 29 日

🇺🇸English

Gmail Skill - Email & Contacts Access

Read, search, and send Gmail emails. Access Google contacts.

CRITICAL: Email Sending Confirmation Required

Before sending ANY email, you MUST get explicit user confirmation.

When the user asks to send an email:

First, show them the complete email details:
- From (which account)
- To
- CC/BCC (if any)
- Subject
- Full body text
Ask: "Do you want me to send this email?"
ONLY run the send command AFTER the user explicitly confirms (e.g., "yes", "send it", "go ahead")
NEVER send an email without this confirmation, even if the user asked you to send it initially

This applies even when:

The user says "send an email to X"
You are in "dangerously skip permissions" mode
The user seems to be in a hurry

Always confirm first. No exceptions.

First-Time Setup (One-Time, ~2 minutes)

On first run, the script will guide you through setup. You need to create a Google Cloud OAuth client once:

Go to Google Cloud Console
Create a project (or select existing)
Enable Gmail API and People API (APIs & Services → Library)
Configure OAuth consent screen:
- User Type: External
- App name: Gmail Skill
- Add yourself as test user
- Add scopes: gmail.readonly, gmail.send, gmail.modify, contacts.readonly
Create OAuth client ID:
- Application type: Desktop app
- Download JSON → save as ~/.claude/skills/gmail-skill/credentials.json

Then just run any command - browser opens, you approve, done. Works for all your accounts.

Note: If you previously used gmail-reader, you'll need to re-authenticate to grant the new gmail.send scope.

Commands

Search Emails

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

Query examples:

from:john@example.com - from specific sender
subject:meeting after:2026/01/01 - subject + date
has:attachment filename:pdf - with PDF attachments
is:unread - unread emails
"exact phrase" - exact match

Read Email

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

List Recent Emails

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

Send Email (Requires Confirmation)

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

Required arguments:

--to / -t - Recipient email address
--subject / -s - Email subject line
--body / -b - Email body text

Optional arguments:

--cc - CC recipients (comma-separated)
--bcc - BCC recipients (comma-separated)
--account / -a - Send from specific account

Example:

python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "recipient@example.com" \
  --subject "Meeting Tomorrow" \
  --body "Hi, just confirming our meeting at 2pm tomorrow." \
  --account work@company.com

Mark as Read

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

Mark as Unread

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

Both mark-read and mark-unread support multiple IDs (comma-separated):

python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read "id1,id2,id3" --account user@gmail.com

Mark Done (Archive)

Archives email(s) by removing from inbox. Equivalent to Gmail's 'e' keyboard shortcut.

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

Unarchive

Moves email(s) back to inbox (undo archive).

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

Star / Unstar

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]

All label commands support multiple IDs (comma-separated):

python3 ~/.claude/skills/gmail-skill/gmail_skill.py star "id1,id2,id3" --account user@gmail.com

Create Draft

Creates a draft email. Use --reply-to-id when replying to an existing email to ensure proper threading in email clients like 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]

Required arguments:

--to / -t - Recipient email address
--subject / -s - Email subject line
--body / -b - Email body text

Optional arguments:

--reply-to-id / -r - Message ID to reply to (adds proper In-Reply-To and References headers for threading)
--cc - CC recipients (comma-separated)
--bcc - BCC recipients (comma-separated)
--account / -a - Create draft in specific account

Example (new email):

python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "recipient@example.com" \
  --subject "Draft for Review" \
  --body "Here's my draft message."

Example (reply to existing email):

python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "sender@example.com" \
  --subject "Re: Original Subject" \
  --body "Thanks for your email..." \
  --reply-to-id 19b99b3127793843 \
  --account work@company.com

List Labels

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

List Contacts

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

Search Contacts

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

Manage Accounts

# 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 user@gmail.com

Multi-Account Support

Add accounts by using --account with a new email - browser opens for that 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 work@company.com

# Add personal account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account personal@gmail.com

# Use specific account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "from:boss" --account work@company.com

Tokens are stored per-account in ~/.claude/skills/gmail-skill/tokens/

Examples

Find unread emails from this week

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

Read a specific email

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

Send a quick email

python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "friend@example.com" \
  --subject "Hello!" \
  --body "Just wanted to say hi."

Find someone's contact info

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

Check work email from personal machine

python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account work@company.com --max-results 5

Output

All commands output JSON for easy parsing.

Requirements

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

Security Notes

Send confirmation required - Claude must always confirm with the user before sending emails
Tokens stored locally in ~/.claude/skills/gmail-skill/tokens/
Revoke access anytime: https://myaccount.google.com/permissions
Apps in "testing" mode may require re-auth every 7 days (publish app to avoid)

Weekly Installs

219

Repository

idanbeck/claude-skills

GitHub Stars

First Seen

Jan 29, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

opencode193

gemini-cli188

codex185

cursor183

github-copilot179

kimi-cli161

Skills CLI 使用指南：AI Agent 技能包管理器安装与管理教程

27,400 周安装