Google Photos MCP サーバー

Google フォト統合のための Model Context Protocol (MCP) サーバーです。Claude、Gemini、その他の AI アシスタントが Google フォトライブラリの写真を読み取り、書き込み、選択できるようにします。

✅ Picker API サポート (2025年3月以降)

このサーバーは Google Photos Picker API を実装しており、2025年3月31日の特定の Library API スコープの廃止後も、ライブラリへのフルアクセスを提供します。

Picker API の仕組み

1. create_picker_session を呼び出す — ユーザーがブラウザで開く URL が返されます

2. ユーザーがライブラリ全体から写真を選択します

3. poll_picker_session を呼び出す — mediaItemsSet が true になると、選択された写真が返されます

Related MCP server: CoreViz MCP

🛡️ セキュリティ通知: CORS の削除

セキュリティ上の理由（localhost へのドライブバイ攻撃を防ぐため）により、CORS ミドルウェアは削除されました。

• ✅ STDIO モード (Claude Desktop): 通常通り動作します

• ✅ ストリーミング HTTP (Cursor, サーバー間): 通常通り動作します

• ❌ ブラウザ AJAX: サポートされていません (設計上の仕様)

機能

読み取り操作

• テキスト、日付、場所、カテゴリ、お気に入りによる写真検索

• メディアタイプ（写真/動画）、日付範囲、アーカイブ状態によるフィルタリング

• base64 エンコードされた画像を含む写真詳細の取得

• アルバムとその内容の一覧表示

• 利用可能なフィルタ機能の説明

書き込み操作

• アルバムの作成と写真のアップロード

• create_album_with_media によるバッチアップロード（最大50ファイル）

• アルバムへのテキストおよび位置情報の追加

• アルバムカバー写真の設定

Picker 操作

• ライブラリ全体にアクセスするための Picker セッションの作成

• セッションのポーリングと選択されたメディアアイテムの取得

インフラストラクチャ

• ⚡ ストリーミング HTTP トランスポート (MCP 2025-06-18 仕様)

• 🔗 接続プーリングを備えた HTTPS Keep-Alive

• 🔒 OS キーチェーンへのトークン保存

• 📊 自動追跡によるクォータ管理

• 🔄 自動トークン更新

前提条件

• Node.js 22.22+

• Photos Library API が有効な Google Cloud プロジェクト

• OAuth 2.0 認証情報 (Web アプリケーションタイプ)

セットアップ

1. Google Cloud のセットアップ

1. Google Cloud Console にアクセスします

2. 新しいプロジェクトを作成（または既存のプロジェクトを選択）します

3. Photos Library API を有効にします

4. OAuth 2.0 認証情報（Web アプリケーション）を作成します

5. http://localhost:3000/auth/callback を承認済みリダイレクト URI として追加します

6. クライアント ID とクライアントシークレットを控えておきます

2. インストール

git clone https://github.com/savethepolarbears/google-photos-mcp.git
cd google-photos-mcp
npm install

3. 設定

cp .env.example .env

.env を編集します:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
PORT=3000
NODE_ENV=development

4. ビルドと実行

npm run build    # Compile TypeScript
npm start        # HTTP mode (for auth & Cursor)
npm run stdio    # STDIO mode (for Claude Desktop)
npm run dev      # Dev mode with live reload

5. 認証

1. HTTP モードで開始: npm start

2. ブラウザで http://localhost:3000/auth にアクセスします

3. Google OAuth フローを完了します

4. トークンは自動的に OS キーチェーンに保存されます

注意: 認証は最初に HTTP モードで完了する必要があります。その後、Claude Desktop 用に STDIO モードに切り替えてください。

動的ポート

PORT=3001 npm start
# Also update GOOGLE_REDIRECT_URI in .env to match

クライアント設定

Claude Desktop (STDIO)

{
  "mcpServers": {
    "google-photos": {
      "command": "node",
      "args": ["/path/to/google-photos-mcp/dist/index.js", "--stdio"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:3000/auth/callback"
      }
    }
  }
}

Cursor IDE

STDIO (推奨):

• Type: Command

• Command: node /path/to/google-photos-mcp/dist/index.js --stdio

HTTP:

• Type: URL

• URL: http://localhost:3000/mcp

Smithery

# Claude Desktop
npx -y @smithery/cli install google-photos-mcp --client claude

# Cursor IDE
npx -y @smithery/cli install google-photos-mcp --client cursor

MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js        # HTTP
npx @modelcontextprotocol/inspector node dist/index.js --stdio # STDIO

利用可能なツール (19)

検索と閲覧

書き込みと管理

Picker API

認証

クエリ例

"Show me photos from my trip to Paris"
"Find photos of my dog from 2024"
"List my photo albums"
"Upload these vacation photos to a new album called 'Summer 2025'"
"Search for landscape photos from last year, ordered newest first"
"Let me pick some photos from my library" (triggers Picker API)

位置情報データ

位置情報は概算であり、OpenStreetMap/Nominatim ジオコーディングを使用して写真の説明から抽出されます。利用可能な場合、緯度/経度、市区町村、地域、国が含まれます。

デプロイ / リリース

このプロジェクトは、Claude Desktop や Cursor などの AI クライアントと一緒にローカルで実行することを目的とした Model Context Protocol (MCP) サーバーです。ローカルのチェックアウトや NPM インストールを最新の状態に保つ以外に、リモートデプロイやリリースプロセスは必要ありません。

トラブルシューティング

• Node バージョン: 古いバージョンはサポートされていないため、Node.js 22.22+ を使用していることを確認してください。

• 認証: GOOGLE_CLIENT_ID is not set エラーが発生したり、認証が失敗したりする場合は、.env ファイルがルートディレクトリに存在し、正しい Google Cloud 認証情報が含まれていることを確認してください。STDIO モードに切り替える前に、必ず npm start (HTTP モード) を実行して認証を行ってください。

• クォータの問題: Google Photos API の制限が適用されます。1日10,000リクエストのクォータ制限に達していないことを確認してください。サーバーは quotaManager を介してこれを追跡します。

• CORS エラー: サーバーはドライブバイ攻撃を防ぐために意図的に CORS を無効にしています。ブラウザの AJAX リクエストから直接サーバーを呼び出そうとしないでください。

開発

プロジェクト構造

src/
├── index.ts              # HTTP entry point
├── dxt-server.ts         # STDIO/DXT entry point
├── mcp/core.ts           # All tool handlers (19 tools)
├── api/
│   ├── client.ts         # REST client (Library + Picker)
│   ├── photos.ts         # Facade module (re-exports)
│   ├── types.ts          # TypeScript interfaces
│   └── repositories/     # Low-level API calls
├── auth/                 # OAuth, tokens, keychain
├── schemas/              # Zod validation schemas
├── utils/                # Config, logging, quota, retry
└── views/                # HTML templates

テスト

npm test              # All tests (Vitest)
npm run test:watch    # Interactive TDD
npm run test:coverage # Coverage report
npm run test:security # Security suite only

品質チェック

マージ前に以下の3つすべてに合格する必要があります:

npx tsc --noEmit   # Type check
npm run lint        # ESLint
npm test            # Tests

ライセンス

MIT