gmail-skill

Gmail スキル - メールと連絡先へのアクセス

Gmail のメールを読み取り、検索、送信できます。Google の連絡先にアクセスできます。

重要：メール送信には確認が必要です

メールを送信する前に、必ずユーザーから明示的な確認を得てください。

ユーザーからメールの送信を依頼された場合：

1. まず、メールの詳細をすべて提示します：
   • From（送信元のアカウント）
   • To
   • CC/BCC（該当する場合）
   • Subject
   • 本文全文
2. 「このメールを送信してもよろしいですか？」と尋ねます。
3. ユーザーが明示的に確認した後にのみ（例：「はい」「送信してください」「進めてください」）、送信コマンドを実行します。
4. ユーザーが最初に送信を依頼していた場合でも、この確認なしにメールを送信してはなりません。

以下の場合も同様です：

• ユーザーが「X にメールを送信して」と言った場合
• 「権限を危険な形でスキップ」モードの場合
• ユーザーが急いでいるように見える場合

必ず最初に確認してください。例外はありません。

初回セットアップ（1 回のみ、約 2 分）

初回実行時に、スクリプトがセットアップを案内します。Google Cloud OAuth クライアントを一度作成する必要があります：

1. Google Cloud Console にアクセスします。
2. プロジェクトを作成するか、既存のものを選択します。
3. Gmail API と People API を有効にします（API とサービス → ライブラリ）。
4. OAuth 同意画面を設定します：
   • ユーザータイプ：外部
   • アプリ名：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 は、マルチパートの alternative メッセージを作成します（プレーンテキスト + シンプルな HTML 段落、強制的な行折り返しなし、適切な大文字・小文字のヘッダー）。この方法で作成した下書きは、スレッド返信や添付ファイルを含め、Superhuman で正しく表示され、編集できます（2026-10-08 に 3 件のカナリア下書きでテスト済み）。

send と draft の両方で使用できる追加オプション：

• --body-file PATH：ファイルから本文を読み込みます（長いメールでシェルの引用符処理を避けられます）。
• --attach PATH：ファイルを添付します（繰り返し指定できます）。
• --reply-to-id MESSAGE_ID：メッセージを返信としてスレッドに追加します（In-Reply-To/References と threadId を設定します）。draft だけでなく send でも使用できます。

推奨するメール送信の流れ：適切なアカウントとスレッドで下書きを作成し、ユーザーが Superhuman で確認して送信します。send を使用するのは、メールごとに明示的な確認を得た後に限ります。

下書きを作成

メールの下書きを作成します。Superhuman などのメールクライアントで適切にスレッド化するには、既存のメールに返信する際に --reply-to-id を使用してください。

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 - CC の受信者（カンマ区切り）
• --bcc - 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 日ごとに再認証が必要になることがあります（回避するにはアプリを公開してください）