gmail

Gmail

スタンドアロンの OAuth 認証を備えた軽量な Gmail 連携です。MCP サーバーは不要です。

⚠️ Google Workspace アカウントが必要です。 個人用 Gmail アカウントには対応していません。

初回セットアップ

Google で認証します（ブラウザーが開きます）。

python scripts/auth.py login

認証状態を確認します。

python scripts/auth.py status

必要に応じてログアウトします。

python scripts/auth.py logout

コマンド

すべての操作は scripts/gmail.py で実行します。ログインしていない場合は、初回使用時に自動で認証されます。

メールを検索する

# Search with Gmail query syntax
python scripts/gmail.py search "from:[email protected] is:unread"

# Search recent emails (no query returns all)
python scripts/gmail.py search --limit 20

# Filter by label
python scripts/gmail.py search --label INBOX --limit 10

# Include spam and trash
python scripts/gmail.py search "subject:important" --include-spam-trash

メールの内容を読む

# Get full message content
python scripts/gmail.py get MESSAGE_ID

# Get just metadata (headers)
python scripts/gmail.py get MESSAGE_ID --format metadata

# Get minimal response (IDs only)
python scripts/gmail.py get MESSAGE_ID --format minimal

メールを送信する

# Send a simple email
python scripts/gmail.py send --to "[email protected]" --subject "Hello" --body "Message body"

# Send with CC and BCC
python scripts/gmail.py send --to "[email protected]" --cc "[email protected]" --bcc "[email protected]" \
  --subject "Team Update" --body "Update message"

# Send from an alias (must be configured in Gmail settings)
python scripts/gmail.py send --to "[email protected]" --subject "Hello" --body "Message" \
  --from "Mile9 Accounts <[email protected]>"

# Send HTML email
python scripts/gmail.py send --to "[email protected]" --subject "HTML Email" \
  --body "<h1>Hello</h1><p>HTML content</p>" --html

下書きを管理する

# Create a draft
python scripts/gmail.py create-draft --to "[email protected]" --subject "Draft Subject" \
  --body "Draft content"

# Send an existing draft
python scripts/gmail.py send-draft DRAFT_ID

メッセージを変更する（ラベル）

# Mark as read (remove UNREAD label)
python scripts/gmail.py modify MESSAGE_ID --remove-label UNREAD

# Mark as unread
python scripts/gmail.py modify MESSAGE_ID --add-label UNREAD

# Archive (remove from INBOX)
python scripts/gmail.py modify MESSAGE_ID --remove-label INBOX

# Star a message
python scripts/gmail.py modify MESSAGE_ID --add-label STARRED

# Unstar a message
python scripts/gmail.py modify MESSAGE_ID --remove-label STARRED

# Mark as important
python scripts/gmail.py modify MESSAGE_ID --add-label IMPORTANT

# Multiple label changes at once
python scripts/gmail.py modify MESSAGE_ID --remove-label UNREAD --add-label STARRED

ラベルを一覧表示する

# List all Gmail labels (system and user-created)
python scripts/gmail.py list-labels

Gmail のクエリ構文

Gmail は強力な検索演算子に対応しています。

クエリ	説明
from:[email protected]	特定の送信者からのメール
to:[email protected]	特定の宛先へのメール
subject:meeting	件名に「meeting」を含むメール
is:unread	未読メール
is:starred	スター付きメール
is:important	重要なメール
has:attachment	添付ファイルのあるメール
after:2024/01/01	指定した日付以降のメール
before:2024/12/31	指定した日付より前のメール
newer_than:7d	過去 7 日間のメール
older_than:1m	1 か月より前のメール
label:work	特定のラベルが付いたメール
in:inbox	受信トレイ内のメール
in:sent	送信済みメール
in:trash	ゴミ箱内のメール

AND（スペース）、OR、または -（NOT）を使って組み合わせます。

python scripts/gmail.py search "from:[email protected] is:unread newer_than:1d"
python scripts/gmail.py search "subject:urgent OR subject:important"
python scripts/gmail.py search "from:[email protected] -is:starred"

よく使われるラベル ID

ラベル	ID
受信トレイ	INBOX
送信済み	SENT
下書き	DRAFT
迷惑メール	SPAM
ゴミ箱	TRASH
スター付き	STARRED
重要	IMPORTANT
未読	UNREAD

トークン管理

トークンはシステムのキーリングを使用して安全に保存されます。

• macOS：キーチェーン
• Windows：Windows 資格情報ロッカー
• Linux：Secret Service API（GNOME Keyring、KDE Wallet など）

サービス名：gmail-skill-oauth

トークンの有効期限が切れると、Google のクラウド関数を使用して自動的に更新されます。