gdrive-access

Google Drive アクセス

Claude Code を介して、Google Drive のファイルをプログラムから一覧表示、ダウンロード、同期します。

自己進化型スキル：このスキルは使用を通じて改善されます。手順が間違っていたり、パラメーターが変わっていたり、回避策が必要になったりした場合は、先延ばしにせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合のみ更新してください。

必須の事前確認（Drive を操作する前に実行）

重要：gdrive コマンドを実行する前に、必ずこの事前確認のチェックリストを完了してください。手順を省略しないでください。

手順 1：CLI バイナリの存在を確認

ls -la "$HOME/.claude/plugins/marketplaces/cc-skills/plugins/productivity-tools/skills/gdrive-access/scripts/gdrive" 2>/dev/null || echo "BINARY_NOT_FOUND"

BINARY_NOT_FOUND の場合：最初にビルドしてください。

cd ~/.claude/plugins/marketplaces/cc-skills/plugins/productivity-tools/skills/gdrive-access/scripts && bun install && bun run build

手順 2：GDRIVE_OP_UUID 環境変数を確認

echo "GDRIVE_OP_UUID: ${GDRIVE_OP_UUID:-NOT_SET}"

NOT_SET の場合：以下のセットアップ手順を必ず実行してください。gdrive コマンドに進まないでください。

手順 3：1Password の認証を確認

op account list 2>&1 | head -3

エラーが発生した場合、またはサインインしていない場合：まず op signin を実行するようユーザーに伝えてください。

---

セットアップ手順（GDRIVE_OP_UUID が NOT_SET の場合）

以下の手順を順番どおりに実行してください。判断が必要な箇所では AskUserQuestion を使用してください。

セットアップ手順 1：1Password CLI を確認

command -v op && echo "OP_CLI_INSTALLED" || echo "OP_CLI_MISSING"

OP_CLI_MISSING の場合：停止して、ユーザーに次のように伝えてください。

1Password CLI が必要です。brew install 1password-cli でインストールしてください。

セットアップ手順 2：1Password で Drive の OAuth アイテムを検索

unset HTTPS_PROXY HTTP_PROXY   # the OAuth proxy 502s api.1password.com
op vault list                  # FIRST: see which vaults this credential can actually reach
op item list --vault "<vault-from-above>" --format json 2>/dev/null | jq -r '.[] | select(.title | test("drive|oauth|google"; "i")) | "\(.id)\t\(.title)"'

⚠ Employee をハードコードしないでください。 op をサービスアカウントのトークンで実行すると、そのトークンに許可された保管庫のみが表示されます。そのため、--vault Employee は "Employee" isn't a vault in this account というエラーになります。結果をそのままパイプで渡すと、これが jq: parse error として分かりにくく表示されることがあります。必ず最初に op vault list を実行し、それに応じて GDRIVE_OP_VAULT を設定してください。また、サービスアカウントでは、すべての op item get に --vault を指定する必要があります。指定しない場合は a vault query must be provided というエラーになります。

出力を解析し、結果に応じて進めてください。

セットアップ手順 3：ユーザーが OAuth 認証情報を選択

アイテムが見つかった場合：見つかったアイテムを提示して AskUserQuestion を使用してください。

AskUserQuestion({
  questions: [{
    question: "Which 1Password item contains your Google Drive OAuth credentials?",
    header: "Drive OAuth",
    options: [
      // POPULATE FROM op item list RESULTS - example:
      { label: "Google Drive API (56peh...)", description: "OAuth client in Employee vault" },
      { label: "Gmail API - project-f (abc12...)", description: "Can also access Drive" },
    ],
    multiSelect: false
  }]
})

アイテムが見つからない場合：セットアップを案内するために AskUserQuestion を使用してください。

AskUserQuestion({
  questions: [{
    question: "No Google Drive OAuth credentials found in 1Password. How would you like to proceed?",
    header: "Setup",
    options: [
      { label: "Create new OAuth credentials (Recommended)", description: "I'll guide you through Google Cloud Console setup" },
      { label: "I have credentials elsewhere", description: "Help me add them to 1Password" },
      { label: "Skip for now", description: "I'll set this up later" }
    ],
    multiSelect: false
  }]
})

• 「新しい OAuth 認証情報を作成する」の場合：references/gdrive-api-setup.md を読み、提示してください。
• 「認証情報は別の場所にある」の場合：必須フィールドを含めて 1Password に追加するようユーザーを案内してください。
• 「今回はスキップ」の場合：設定が完了するまでこのスキルは動作しないことをユーザーに伝えてください。

セットアップ手順 4：環境設定を確認

CLI は、プロセス環境から GDRIVE_OP_UUID（および任意で GDRIVE_OP_VAULT）のみを読み込みます。ユーザーがアイテム（UUID を含む）を選択したら、AskUserQuestion を使用してください。

AskUserQuestion({
  questions: [{
    question: "Export GDRIVE_OP_UUID from your shell profile (~/.zshrc)?",
    header: "Configure",
    options: [
      { label: "Yes, add to ~/.zshrc (Recommended)", description: "Appends an export line; applies to every new shell" },
      { label: "Show me the line only", description: "I'll add it manually, or pass it inline per call" }
    ],
    multiSelect: false
  }]
})

「はい、~/.zshrc に追加する」の場合：既存の GDRIVE_OP_UUID export がないことを確認してから、次を追記してください。

export GDRIVE_OP_UUID="<selected-uuid>"
export GDRIVE_OP_VAULT="<vault-from-step-2>"   # only if not Employee

「行だけ表示する」の場合：ユーザーが手動で追加できるよう、export 行を出力してください。各呼び出し時に変数をインラインで渡す方法（手順 6 のように GDRIVE_OP_UUID=<uuid> gdrive ... とする方法）も使用できます。

セットアップ手順 5：再読み込みと確認

source ~/.zshrc && echo "GDRIVE_OP_UUID after reload: ${GDRIVE_OP_UUID:-NOT_SET}"

依然として NOT_SET の場合：シェルを再起動するようユーザーに伝えてください。

セットアップ手順 6：接続をテスト

GDRIVE_OP_UUID="${GDRIVE_OP_UUID}" $HOME/.claude/plugins/marketplaces/cc-skills/plugins/productivity-tools/skills/gdrive-access/scripts/gdrive list 1wqqqvBmeUFYuwOOEQhzoChC7KzAk-mAS

OAuth のプロンプトが表示された場合：初回実行時は想定どおりです。Google の同意画面を表示するため、ブラウザーが開きます。

---

Drive コマンド（事前確認に合格した後のみ）

GDRIVE_CLI="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/productivity-tools/skills/gdrive-access/scripts/gdrive"

# List files in a folder
$GDRIVE_CLI list <folder_id>

# List with details (size, modified date)
$GDRIVE_CLI list <folder_id> --verbose

# Search for files
$GDRIVE_CLI search "name contains 'training'"

# Get file info
$GDRIVE_CLI info <file_id>

# Download a single file
$GDRIVE_CLI download <file_id> -o ./output.pdf

# Sync entire folder to local directory
$GDRIVE_CLI sync <folder_id> -o ./output_dir

# Sync with subfolders
$GDRIVE_CLI sync <folder_id> -o ./output_dir -r

# JSON output (for parsing)
$GDRIVE_CLI list <folder_id> --json

ネイティブ Google ドキュメントの作成（書き込み）

create-doc はローカルの HTML（または .docx）ソースをアップロードし、Drive に変換させて ネイティブ Google ドキュメント（application/vnd.google-apps.document）を作成します。チームは「変換」手順を挟まずに、直接開いてコメントできます。これは Drive で推奨されるパターンです。メタデータに 変換後の mimeType、メディアに ソースのバイト列を指定し、マルチパート アップロードとして files.create を送信します（単純アップロードでは変換が暗黙にスキップされます）。

# Markdown is the usual author format → HTML (highest-fidelity import) → native Google Doc
pandoc notes.md -o /tmp/notes.html --standalone
$GDRIVE_CLI create-doc /tmp/notes.html --name "Meeting Notes" --parent <folder_id>
# → prints the new Doc's id, mimeType (application/vnd.google-apps.document), and docs.google.com link

# Overwrite an existing Doc's contents in place (keeps the same id / link / comments):
$GDRIVE_CLI create-doc /tmp/notes.html --update <doc_id>

rclone／.docx ではだめな理由。 rclone の --drive-import-formats はこの用途では信頼性に欠け（名前の衝突や同期の混乱などの落とし穴があります）、Drive 上の通常の .docx は Docs で開けますが、ネイティブ ドキュメントではありません。上記の Drive API による変換が、堅牢な FOSS の方法です。

書き込みスコープ（再認証は初回のみ）。 create-doc には drive.file スコープが必要です（このアプリが作成するファイルの作成・管理に限定され、最小権限であり、全ドライブへのアクセスではありません）。これは元の drive.readonly と同時に追加されたため、初回の書き込み時に同意を求めるプロンプトが再度表示されます。表示されない場合は、次のコマンドで強制してください。 rm ~/.claude/tools/gdrive-tokens/$GDRIVE_OP_UUID.json を実行してから、もう一度実行します。--update が機能するのは、このアプリが作成した Docs に限られます（drive.file の制約）。外部で作成された Docs を上書きするには、スコープを auth/drive に広げてください。

レート制限と再試行（組み込み）

プロジェクトが短時間にクエリを送りすぎると、Drive は HTTP 403 rateLimitExceeded／userRateLimitExceeded（場合によっては 429）を返します。連続して複数回書き込んだ際に、この問題が発生しました。CLI は現在、すべての Drive 呼び出しを ジッター付き指数バックオフ（lib/drive.ts の withBackoff）でラップしています。Google の公式ガイダンスに従い、min(2^n·1000 + random_ms, 64s) の時間待機し、再試行回数には上限があります。レート制限以外のエラーは引き続きそのまま失敗します。事前に制限を超えないようにするには、一括操作をまとめる／間隔を空ける、不要なメタデータ呼び出しを避ける、呼び出しのたびにトークンを更新しない、といった対策をしてください。

保存されたトークンが無効な場合：Error: invalid_grant

Token expired, refreshing... の後に Error: invalid_grant が表示される場合、保存された リフレッシュトークンが取り消されているか、期限切れになっています。アクセストークンの問題ではありません。リフレッシュしても復旧できません。原因としては、OAuth クライアントの Google Cloud における公開ステータスが **「Testing」**のままであること（この場合、リフレッシュトークンは 7 日後に期限切れになります）、ユーザーがアプリへのアクセスを取り消したこと、パスワードが変更されたことが考えられます。この CLI で解決するには、対話型ブラウザーが必要な、同意の完全なやり直ししかありません。

rm ~/.claude/tools/gdrive-tokens/$GDRIVE_OP_UUID.json   # then re-run any gdrive command

ブラウザー不要の代替手段：rclone。 rclone listremotes に同じ Google アカウントの type = drive リモートが表示される場合、独立したトークンが保持されているため、通常は引き続き使用できます。invalid_grant により CLI が完全に使用できなくなった際に、2026-09-02 に動作を確認済みです。「共有アイテム」にあるフォルダーも含め、任意のフォルダーに ID でアクセスできます。「共有アイテム」にはマイドライブのパスがないためです。

rclone lsjson --recursive --max-depth 2 --drive-root-folder-id <folder_id> <remote>:
rclone lsjson --metadata --drive-root-folder-id <folder_id> <remote>:<subfolder>   # adds owner + btime (created)
rclone copy --drive-root-folder-id <folder_id> "<remote>:<subfolder>/<file>" ./dest/

所有者と**作成日時（btime）**を取得するには、--metadata を使うしかありません。通常の lsjson では、どちらも返されません。どのパスを使ったか、必ず報告してください。rclone のリモートは GDRIVE_OP_UUID とは別の Google アカウントである可能性があります。

URL からフォルダー ID を抽出する

Google Drive のフォルダー URL：

https://drive.google.com/drive/folders/1wqqqvBmeUFYuwOOEQhzoChC7KzAk-mAS
                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                       This is the folder ID

Drive の検索構文

クエリ	説明
name contains 'keyword'	名前にキーワードを含む
name = 'exact name'	名前が完全一致
mimeType = 'application/pdf'	ファイルの種類で検索
modifiedTime > '2026-01-01'	指定日以降に更新
trashed = false	ゴミ箱にない
'<folderId>' in parents	指定フォルダー内

参考資料：https://developers.google.com/drive/api/guides/search-files

環境変数

変数	必須	説明
GDRIVE_OP_UUID	はい	OAuth 認証情報の 1Password アイテム UUID
GDRIVE_OP_VAULT	通常	1Password ボールト。コードのデフォルトは Employee ですが、通常、サービスアカウントのトークンからは参照できません。op vault list を実行し、明示的に設定してください

トークンの保存

OAuth トークンの保存先：~/.claude/tools/gdrive-tokens/<uuid>.json

• 中央の場所（プラグイン内でもプロジェクト内でもありません）
• 1Password UUID ごとに整理（複数アカウントに対応）
• chmod 600 で作成

Google Docs のエクスポート

Google Docs（Docs、Sheets、Slides）は自動的にエクスポートされます。

Google の種類	エクスポート形式
ドキュメント	.docx
スプレッドシート	.xlsx
プレゼンテーション	.pptx
図形描画	.png

参考資料

• gdrive-api-setup.md - Google Cloud OAuth のセットアップガイド

変更後のチェックリスト

• YAML フロントマターが有効（説明にコロンがない）
• トリガーキーワードが最新
• パスのパターンでハードコードされたパスではなく $HOME を使用
• 参考資料が存在し、リンクされている

実行後の振り返り

このスキルの実行後、タスクを終了する前に振り返ってください。

0. 自分の場所を確認する。 — 編集する前に、この SKILL.md の正式なパスを確認します。
1. 何が失敗したか？ — 原因となった指示を修正します。
2. 予想以上にうまくいったことは？ — 推奨されるプラクティスとして取り入れます。
3. 何が実態とずれていたか？ — 現状に合わなくなったスクリプト、参考資料、依存関係を修正します。
4. 記録する。 — トリガー、修正内容、根拠を含む進化ログのエントリーを作成します。

先送りしないでください。次回の実行には、あなたが残した状態が引き継がれます。