gmail について
gmailは、Gmail APIでメールを検索・取得するコマンドラインスキルです。メール、ラベル、添付ファイルを扱いたいユーザー向けで、Gmail標準の検索構文、アクセス範囲の設定、MarkdownとJSONの出力に対応しています。
主な機能
- 01テキスト検索や条件指定でメール検索
- 02Gmail標準の検索構文に対応
- 03メール詳細とラベルの表示
- 04メール添付ファイルのダウンロード
- 05MarkdownまたはJSONで出力
活用シーン
- 01送信者や件名を指定してメールを検索
- 02未読、添付あり、日付指定でメールを絞り込み
- 03メール本文の確認と添付ファイルの取得
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/gmailを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
README.md.claude-plugin/plugin.jsonscripts/gmail_search.py詳細
Gmail 検索スキル
柔軟なクエリオプションと出力形式を使って、Gmail API 経由でメールを検索、取得します。
前提条件
認証情報は ~/.gmail_credentials/ に設定する必要があります。setup を実行して状態を確認してください。
python3 scripts/gmail_search.py setup
Gmail API 認証情報の取得
1. Google Cloud プロジェクトを作成する
- console.cloud.google.com にアクセスします
- プロジェクトのドロップダウンをクリックし、「新しいプロジェクト」を選択します
- 名前（例：「Gmail Agent Skill」）を入力し、「作成」をクリックします
2. Gmail API を有効にする
- 「API とサービス」->「ライブラリ」に移動します
- 「Gmail API」を検索します
- クリックして「有効にする」をクリックします
3. OAuth 同意画面を設定する
- 左側のサイドバーで「OAuth 同意画面」に移動します
- ユーザーの種類として「外部」を選択します
- 必須項目を入力します：
- アプリ名：Gmail Agent Skill
- ユーザーサポートメール：自分のメールアドレス
- デベロッパーの連絡先情報：自分のメールアドレス
- 「保存して次へ」をクリックし、スコープはスキップします
- 「テストユーザー」ページで、自分の Gmail アドレスを追加します
- すべての手順を完了します
4. テストアプリを公開する
重要： この手順を行わないと、「Error 403: access_denied」が表示されます。
- 「OAuth 同意画面」に戻ります
- 「公開ステータス」で「アプリを公開」をクリックします
- ダイアログで確定します
これによりアプリはテストモード（本番環境ではありません）のままですが、テストユーザーが認証できるようになります。ログイン時に「未確認のアプリ」という警告が表示されます。「詳細設定」->「Gmail Agent Skill（安全ではないページ）に移動」をクリックして続行してください。
注： テスト用トークンの有効期限は7日間です。本番環境で使用するには Google による確認が必要です。
5. OAuth 認証情報を作成する
- 左側のサイドバーで「認証情報」に移動します
- 「認証情報を作成」->「OAuth クライアント ID」をクリックします
- アプリケーションの種類として「デスクトップアプリ」を選択します
- 名前（例：「Gmail Agent Client」）を入力します
- 「作成」をクリックします
6. 認証情報を取得する
- クライアント ID が表示されるので、コピーします
- クライアントシークレット：ダウンロードアイコンをクリックするか、詳細を表示してシークレットを取得します
7. 認証情報を保存する
~/.gmail_credentials/credentials.json を作成します：
{
"installed": {
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"redirect_uris": ["http://localhost"]
}
}
8. 認証する
python3 scripts/gmail_search.py auth
ブラウザーが開きます。「未確認のアプリ」という警告（「詳細設定」->「Gmail Agent Skill に移動」）を進み、アクセスを許可すれば準備完了です。
クイックスタート
# Check setup status
python3 scripts/gmail_search.py setup
# Authenticate (opens browser)
python3 scripts/gmail_search.py auth
# Search emails
python3 scripts/gmail_search.py search "meeting notes"
# Search with filters
python3 scripts/gmail_search.py search --from "[email protected]" --unread
コマンド
セットアップ
設定の状態を確認します：
python3 scripts/gmail_search.py setup
python3 scripts/gmail_search.py setup --json
認証
Gmail で認証します（OAuth 用のブラウザーが開きます）：
python3 scripts/gmail_search.py auth
スコープ
API の権限スコープを表示または変更します：
# View current scope
python3 scripts/gmail_search.py scope
# Change scope (requires re-auth)
python3 scripts/gmail_search.py scope --set readonly
python3 scripts/gmail_search.py scope --set modify
python3 scripts/gmail_search.py scope --set full
使用可能なスコープ：
readonly- メールの読み取りのみ（デフォルト、推奨）modify- 読み取り + ラベルの変更、既読／未読の設定full- 削除を含むフルアクセス
検索
フリーテキストクエリまたはフィルターを使ってメールを検索します：
# Free-text search (uses Gmail search syntax)
python3 scripts/gmail_search.py search "project deadline"
python3 scripts/gmail_search.py search "from:[email protected] subject:invoice"
# Using helper flags
python3 scripts/gmail_search.py search --from "[email protected]"
python3 scripts/gmail_search.py search --to "[email protected]"
python3 scripts/gmail_search.py search --subject "Weekly Report"
python3 scripts/gmail_search.py search --label "INBOX"
python3 scripts/gmail_search.py search --label "work"
# Date filters (YYYY/MM/DD format)
python3 scripts/gmail_search.py search --after 2024/01/01
python3 scripts/gmail_search.py search --before 2024/12/31
python3 scripts/gmail_search.py search --after 2024/01/01 --before 2024/06/30
# Status filters
python3 scripts/gmail_search.py search --unread
python3 scripts/gmail_search.py search --starred
python3 scripts/gmail_search.py search --has-attachment
# Combined filters
python3 scripts/gmail_search.py search "invoice" --from "billing@" --has-attachment --after 2024/01/01
# Limit results
python3 scripts/gmail_search.py search "meeting" --limit 50
# Include full body (default shows snippet only)
python3 scripts/gmail_search.py search "contract" --full
# Include attachment info
python3 scripts/gmail_search.py search --has-attachment --attachments
# JSON output
python3 scripts/gmail_search.py search "project" --json
添付ファイルのダウンロード
特定のメッセージから添付ファイルをダウンロードします：
# Download to default location (~/Downloads/gmail_attachments/)
python3 scripts/gmail_search.py download MESSAGE_ID
# Download to custom directory
python3 scripts/gmail_search.py download MESSAGE_ID --output /path/to/folder
# JSON output
python3 scripts/gmail_search.py download MESSAGE_ID --json
検索結果に表示されるメッセージ ID を取得してください。
ラベル
使用可能な Gmail ラベルをすべて一覧表示します：
python3 scripts/gmail_search.py labels
python3 scripts/gmail_search.py labels --json
出力形式
Markdown（デフォルト）
# Gmail Search Results (3 messages)
## Weekly Report
**From:** [email protected]
**To:** [email protected]
**Date:** Mon, 25 Nov 2024 10:00:00 +0000
**ID:** `18abc123def`
> Here's the weekly report summary...
---
JSON
構造化された出力を得るには、--json フラグを追加します：
[
{
"id": "18abc123def",
"thread_id": "18abc123def",
"from": "[email protected]",
"to": "[email protected]",
"subject": "Weekly Report",
"date": "Mon, 25 Nov 2024 10:00:00 +0000",
"snippet": "Here's the weekly report summary...",
"labels": ["INBOX", "UNREAD"]
}
]
Gmail 検索構文
このスキルでは、フリーテキストクエリで Gmail 固有の検索構文を使用できます：
| 演算子 | 例 | 説明 |
|---|---|---|
from: | from:[email protected] | 特定の送信者から |
to: | to:[email protected] | 特定の宛先へ |
subject: | subject:meeting | 件名内 |
label: | label:work | 特定のラベルが付いている |
has:attachment | has:attachment | 添付ファイルがある |
filename: | filename:pdf | 添付ファイル名 |
is:unread | is:unread | 未読メッセージ |
is:starred | is:starred | スター付きメッセージ |
after: | after:2024/01/01 | 指定日より後 |
before: | before:2024/12/31 | 指定日より前 |
newer_than: | newer_than:7d | 過去 N 日以内 |
older_than: | older_than:1m | N か月より前 |
in: | in:inbox | 特定のフォルダー内 |
OR | from:john OR from:jane | いずれかの条件 |
- | -label:spam | 除外 |
"" | "exact phrase" | 完全一致 |
ユーザーのリクエスト例
| ユーザーの発言 | コマンド |
|---|---|
| 「会議メモを Gmail で検索して」 | search "meeting notes" |
| 「John からのメールを探して」 | search --from "john" |
| 「未読メールを表示して」 | search --unread |
| 「先月のプロジェクトに関するメール」 | search "project" --after 2024/10/01 |
| 「添付ファイル付きの請求書」 | search "invoice" --has-attachment |
| 「契約に関するメールの全文を読んで」 | search "contract" --full --limit 1 |
| 「そのメールの添付ファイルをダウンロードして」 | download MESSAGE_ID |
| 「どんなラベルがありますか？」 | labels |
| 「上司からのスター付きメール」 | search --from "boss" --starred |
| 「Gmail は設定されていますか？」 | setup |
依存関係
pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib
ファイル
~/.gmail_credentials/credentials.json- OAuth クライアントの認証情報~/.gmail_credentials/token.pickle- キャッシュされた認証トークン~/.gmail_credentials/scope.txt- 現在のスコープ設定
コメント
Markdown 対応