Photos Macos MCP

🚀 PhotosMCP

PhotosMCP 是一個用 Swift 編寫的 模型上下文協議（MCP）服務器，它藉助蘋果的 PhotoKit 框架，為 AI 助手提供對 macOS 照片庫的只讀訪問權限。

🚀 快速開始

環境要求

• macOS 13.0 及以上版本
• Swift 6.0 及以上版本（Xcode 16 及以上）
• 安裝有照片庫的照片應用程序

構建項目

在終端中執行以下命令來構建項目：

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. 授予照片訪問權限： PhotosMCP 進程（或其父級 Claude 應用）需要訪問你的照片庫。如果系統提示，請在 系統設置 → 隱私與安全 → 照片 中授予訪問權限。 如果服務器是由 Claude 桌面應用啟動的，你可能需要授予 Claude 應用訪問照片的權限。
4. 重啟 Claude：重啟 Claude 桌面應用，使其加載新的 MCP 服務器。

✨ 主要特性

MCP 工具

所有列表/搜索工具都支持 limit（默認值為 50，最大值為 200）和 offset 參數，用於分頁操作。

權限管理

服務器使用 PHPhotoLibrary.requestAuthorization 方法，首次使用時會顯示系統對話框。如果訪問被拒絕，工具會返回明確的錯誤消息。

只讀訪問

該服務器僅提供只讀訪問權限，不會修改、刪除或創建資產或相冊。

隱私與數據處理

• 地點搜索（get_photos_by_place）：你提供的地點名稱（如“瓦倫西亞”、“巴黎”）會被髮送到蘋果的地理編碼服務以解析座標，這可能涉及網絡請求。
• 圖像導出：縮略圖和全分辨率圖像會被寫入系統臨時文件夾的 PhotosMCP 子目錄中。新導出圖像時，超過 1 小時的文件會被自動刪除。

🔧 技術細節

項目結構

PhotosMCP/
├── Package.swift
├── Info.plist              # 用於照片訪問的 NSPhotoLibraryUsageDescription
├── Sources/
│   └── PhotosMCP/
│       ├── main.swift              # 入口點，標準輸入輸出傳輸
│       ├── 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         # 用於位置搜索的 Haversine 距離計算
│           └── 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 許可證。