← cloudfetch 目次へ ／ サイトトップ

CF-001

cloudfetch / photofetch — スマホ写真を Drive 経由で取得し Claude / Antigravity に解析させる仕組み

作成: 2026-06-21 ／ カテゴリ: 技術（CLI ツール・自動化）

このノートの要約。 cloudfetch は、Android スマホで撮った写真を Google Drive 上の専用フォルダ経由でローカルに取り込み、Claude Code（Max プラン）または Antigravity（Google AI Pro）に Vision でその場で解析させるための個人用 Python CLI（コマンド名は photofetch）です。Google Photos Library API が 2025-04 以降「第三者アプリは Picker API 経由のユーザー手動選択しかできない」よう制限されたため、自動化のためにDrive フォルダ運用に倒した設計です。本ノートは、全体アーキテクチャ・OAuth セットアップ・md5 重複防止ロジック・Drive vs Photos API の制約・ファイル構成・Windows / Mac の起動方法・設計判断と既知の制約をまとめます。
本ノートでの用語規約。
目次
  1. 背景 — なぜ Drive 経由なのか
  2. 全体アーキテクチャ
  3. リポジトリ構成
  4. OAuth 2.0 セットアップシーケンス
  5. md5 ベース重複防止フロー
  6. Drive vs Google Photos API の制約比較
  7. Windows での起動方法
  8. Mac での起動方法
  9. OCR と AI 解析の役割分担
  10. 設計判断のサマリ
  11. 既知の制約・注意点
  12. 関連リンク

1. 背景 — なぜ Drive 経由なのか

当初は Google Photos Library API でスマホのカメラロールから直接画像を取得する設計を検討した。しかし 2025-04 の Google の API ポリシー変更で、第三者アプリは Picker API（ユーザーが毎回 GUI で手動選択）を経由しないと Photos ライブラリにアクセスできなくなった。これでは「今日撮った写真をワンコマンドで取り込んで Claude に渡す」という自動化要件を満たせない。🟢 公式アナウンス確認済

一方 Google Drive API は今もフォルダ単位の自動同期が可能で、md5Checksum・imageMediaMetadata といったメタデータも取得できる。そこで「スマホの Drive アプリで専用フォルダに写真をアップ → CLI が定期的に取りに行く」というシンプルな運用に倒した。🟢 Drive API v3 公式ドキュメントで確認済

2. 全体アーキテクチャ

Android からローカルマシン、そして AI への流れを 1 本の図にまとめる。

Android スマホ カメラで撮影 Drive アプリでアップロード Google Drive 専用フォルダ md5Checksum / EXIF を保持 photofetch CLI Python + uv tool global ───────────── OAuth 2.0 (~/.photofetch/) 日付フィルタ検索 md5 重複防止 EXIF / GPS 抽出 日付別フォルダに保存 ./photos/ YYYY-MM-DD/*.jpg metadata/*.json Claude Code (Max) ／ Antigravity (Google AI Pro) Vision で画像内容を解析 サブスク枠を活用 (API 課金回避) 同期 API 保存 画像渡し
図 1. 全体データフロー — Android → Drive → photofetch CLI → ローカル → Claude / Antigravity

3. リポジトリ構成

リポジトリのファイル配置を図にする。Skill ファイルだけ Claude Code のグローバルスキルディレクトリにコピーする運用なので、リポジトリ内では skill/ に置いてある。

cloudfetch/ pyproject.toml 依存と CLI エントリポイント定義 uv.lock 依存ロック (再現性) .gitignore / README.md 写真・認証情報を除外 / 全体説明 .claude/settings.json worklog SessionStart フック docs/ worklog.md / SETUP_MAC.md skill/SKILL.md ~/.claude/skills/photofetch/ にコピー用 src/photofetch/ Python パッケージ本体 __init__.py / cli.py argparse エントリポイント auth.py / drive.py OAuth と Drive API ラッパ exif.py / ocr.py / index.py EXIF 抽出 / OCR / 重複 index photos/ (gitignore) ダウンロード先 — リポジトリに含めない
図 2. リポジトリ構成 — 認証情報と写真本体は Git から除外

4. OAuth 2.0 セットアップシーケンス

初回だけ Google Cloud Console での設定が必要。以降は token のリフレッシュで自動継続する。

User (lunelukkio) Google Cloud Console photofetch CLI Browser / OAuth Server 1. Drive API 有効化 + OAuth Client 作成 2. client_secret.json 発行 3. ~/.photofetch/client_secret.json に配置 4. photofetch login 5. ブラウザで認可ページ起動 6. authorization code 返却 7. access / refresh token 交換 8. ~/.photofetch/token.json に保存 — 以降自動リフレッシュ
図 3. OAuth セットアップシーケンス — 初回のみ手動。token は ~/.photofetch/ に永続化

必要な情報

5. md5 ベース重複防止フロー

「同じ写真を 2 回ダウンロードしない」「index.json を消しても／別の経路（MCP 等）で既に取得済みでも、重複ダウンロードを避ける」ことを保証するため、ローカル全体の md5 スキャンと index.json のキャッシュを併用している。

sync コマンド開始 日付フィルタで Drive を検索 ローカル全体を md5 スキャン 既存 index のエントリは キャッシュ再利用 → md5 → path マップ構築 Drive ファイルを 1 件ずつ判定 分岐 どの状態か index に fileId あり → そのままスキップ md5 がローカルに既に存在 → スキップ＋index に記録 どちらでもない → ダウンロード＋index に記録
図 4. md5 重複防止 — index.json と md5 スキャンの 2 段構え

なぜ md5 スキャンも併用するのか

6. Drive vs Google Photos API の制約比較

項目Google Drive APIGoogle Photos Library API
2025-04 以降の制限従来通り、フォルダ単位で API アクセス可第三者アプリは Picker API 経由の 手動選択のみ
自動同期可能（フォルダを巡回）不可（毎回 GUI が必要）
md5 取得md5Checksum フィールドありなし
EXIF / GPSimageMediaMetadata で取得可一部のみ・形式が異なる
運用負荷スマホ Drive アプリでフォルダにアップAPI 経由の自動化が事実上不可
採用判断採用不採用

7. Windows での起動方法

cd C:\Users\lunel\Projects\Others\cloudfetch
uv tool install --from . photofetch       # photofetch コマンドをグローバル化

# Google Cloud Console で OAuth クライアントを作り、client_secret.json を取得
# それを ~/.photofetch/client_secret.json に配置

photofetch login                          # 初回のみブラウザ認証

# 日常使用
photofetch sync today --ocr-source none
photofetch sync yesterday
photofetch sync 2026-06-21
photofetch sync last:7d
photofetch sync 2026-06-01..2026-06-21

# Claude Code から
/photofetch today

8. Mac での起動方法

詳細は docs/SETUP_MAC.md 参照。要点だけ:

curl -LsSf https://astral.sh/uv/install.sh | sh   # uv 導入
git clone <your-repo>
cd cloudfetch
uv tool install --from . photofetch

# 認証情報の選択肢
# (a) Windows と同じ Google アカウントなら token.json をコピーして共有
# (b) または改めて photofetch login

# Skill を Claude Code に登録
mkdir -p ~/.claude/skills/photofetch
cp skill/SKILL.md ~/.claude/skills/photofetch/

9. OCR と AI 解析の役割分担

CLI はダウンロードと EXIF/GPS 抽出だけに絞っている。画像内容そのもの（OCR・物体認識・要約）は AI 側に任せる。

なぜ Drive 側に OCR を任せないか。 Drive API v3 の公開仕様には、画像 OCR テキストを返すフィールドは存在しない。--ocr-source drive オプションは設計時に検討したが、対応する API が無いため不採用。🟢 公式ドキュメントで確認済

10. 設計判断のサマリ

判断選んだ方向理由
取得元Google DrivePhotos API は手動選択強制 (2025-04 〜)
OCR の場所CLI には入れないClaude / Antigravity の Vision で十分・API 課金回避
重複防止index.json + md5 ローカルスキャンindex 消失や別経路ダウンロードに頑健
配布方法uv tool installグローバルコマンド化・依存衝突なし
Skill 化/photofetch として登録Claude Code から自然言語で呼べる

11. 既知の制約・注意点

12. 関連リンク

確信度ラベル: 本ノートの技術仕様の大半は実装済みコード・公式ドキュメントから確認済（🟢）。Antigravity の挙動はユーザの利用ログに基づく所感（🟡）を含む。