Photos Macos MCP

🚀 PhotosMCP

Swiftで実装されたModel Context Protocol (MCP)サーバーです。AppleのPhotoKitフレームワークを介して、AIアシスタントにmacOSのPhotosライブラリへの読み取り専用アクセスを提供します。

🚀 クイックスタート

必要条件

• macOS 13.0以上
• Swift 6.0以上 (Xcode 16以上)
• ライブラリがあるPhotosアプリ

ビルド方法

swift build -c release

実行可能ファイルは以下の場所に配置されます。

.build/release/PhotosMCP

Claudeデスクトップアプリとの統合

1. プロジェクトをビルド (上記参照)。

2. Claudeデスクトップの設定に追加

   ~/Library/Application Support/Claude/claude_desktop_config.jsonを編集します。

   {
     "mcpServers": {
       "photos": {
         "command": "/Users/YOUR_USERNAME/Developer/photos-macos-mcp/.build/release/PhotosMCP",
         "args": []
       }
     }
   }
   

   YOUR_USERNAME (またはパス全体) をビルドしたバイナリの実際の絶対パスに置き換えます。例えば：

"command": "/Users/max/Developer/photos-macos-mcp/.build/release/PhotosMCP"

3. Photosアクセスを許可

   PhotosMCPプロセス (または親のClaudeアプリ) は、Photosライブラリへのアクセスが必要です。プロンプトが表示された場合は、以下の場所で許可します。 システム設定 → プライバシーとセキュリティ → 写真

   サーバーがClaudeデスクトップアプリによって起動された場合、ClaudeアプリにPhotosアクセスを許可する必要がある場合があります。

4. Claudeを再起動 して、新しいMCPサーバーを認識させます。

✨ 主な機能

MCPツール

すべてのリスト/検索ツールは、ページネーションのためのlimit (デフォルト50、最大200) とoffsetをサポートしています。

権限について

サーバーはPHPhotoLibrary.requestAuthorizationを使用し、初回使用時にシステムダイアログが表示されます。アクセスが拒否された場合、ツールは明確なエラーメッセージを返します。

読み取り専用

このサーバーは読み取り専用です。アセットやアルバムの変更、削除、作成は行いません。

プライバシーとデータ

• 場所検索 (get_photos_by_place)：指定した場所名 (例: "バレンシア", "パリ") は、座標を解決するためにAppleのジオコーディングサービスに送信されます。これにはネットワークリクエストが必要になる場合があります。
• 画像エクスポート：サムネイルと全解像度の画像は、システムの一時フォルダ内のPhotosMCPサブディレクトリに書き込まれます。新しいエクスポートが行われると、1時間以上前のファイルは自動的に削除されます。

🔧 技術詳細

プロジェクト構造

PhotosMCP/
├── Package.swift
├── Info.plist              # NSPhotoLibraryUsageDescription for Photos access
├── Sources/
│   └── PhotosMCP/
│       ├── main.swift              # エントリーポイント、stdioトランスポート
│       ├── PhotosServer.swift      # MCPサーバー、ツール登録
│       ├── Tools/
│       │   ├── ToolDefinitions.swift  # ツールスキーマ
│       │   ├── LibraryTools.swift    # list_albums, get_library_stats, list_moments
│       │   ├── SearchTools.swift     # search_photos, get_photos_by_location, get_photos_by_date
│       │   ├── AlbumTools.swift      # get_album_contents
│       │   ├── AssetTools.swift      # get_asset_details
│       │   └── ImageTools.swift      # get_photo_thumbnail, get_photo_full
│       └── Helpers/
│           ├── PhotoKitHelpers.swift  # PHAsset → JSON構造体
│           ├── ImageExport.swift      # PHImageManager, base64 JPEG
│           ├── PhotosAccess.swift     # ライブラリの認証
│           ├── DateParsing.swift      # ISO 8601日付解析
│           ├── GeoUtils.swift         # 位置検索のためのハーベルサイン距離
│           └── ContentClassifier.swift # Vision MLキーワードマッチング
└── README.md

注意事項

• list_momentsはmacOSでは空のリストを返します。fetchMoments APIはiOS専用です。
• search_photosのキーワード検索は、Vision ML (ピザ、食べ物、車、都市、犬、ビーチなど) を使用します。最大1000枚の写真を分析します—大規模なライブラリの場合は日付範囲と組み合わせて使用してください。
• 場所検索 (get_photos_by_place) は、"バレンシア"、"パリ" などの場所名をジオコーディングし、そこで撮影された写真を見つけます。
• 日付検索はyyyy-MM-ddまたは完全なISO 8601形式を受け付けます。範囲指定にはstart_dateとend_dateを使用してください。

📄 ライセンス

MIT