Photos Macos MCP

🚀 PhotosMCP

A Model Context Protocol (MCP) server written in Swift, which enables AI assistants to access the macOS Photos library in read - only mode through Apple's PhotoKit framework.

🚀 Quick Start

Requirements

• macOS 13.0+
• Swift 6.0+ (Xcode 16+)
• Photos app with a library

Building

swift build -c release

The executable will be located at:

.build/release/PhotosMCP

💻 Usage Examples

Claude Desktop App Integration

1. Build the project (refer to the building section above).
2. Add to Claude Desktop config Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

   Replace YOUR_USERNAME (or the entire path) with the actual absolute path to your built binary. For example:

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

3. Grant Photos access The PhotosMCP process (or the parent Claude app) requires access to your Photos library. If prompted, allow it in: System Settings → Privacy & Security → Photos If the server is launched by the Claude desktop app, you may need to grant Photos access to the Claude app.
4. Restart Claude so that it can recognize the new MCP server.

MCP Tools

All list/search tools support limit (default 50, max 200) and offset for pagination.

🔧 Technical Details

Permissions

The server uses PHPhotoLibrary.requestAuthorization and will display a system dialog upon first use. If access is denied, the tools will return clear error messages.

Read - Only

This server is read - only. It does not modify, delete, or create assets or albums.

Privacy & Data

• Place search (get_photos_by_place): The place names you provide (e.g., "Valencia", "Paris") are sent to Apple's geocoding service to resolve coordinates. This may involve network requests.
• Image export: Thumbnails and full images are written to a PhotosMCP subdirectory in the system temp folder. Files older than 1 hour are automatically deleted when new exports occur.

Project Structure

PhotosMCP/
├── Package.swift
├── Info.plist              # NSPhotoLibraryUsageDescription for Photos access
├── Sources/
│   └── PhotosMCP/
│       ├── main.swift              # Entry point, stdio transport
│       ├── PhotosServer.swift      # MCP server, tool registration
│       ├── Tools/
│       │   ├── ToolDefinitions.swift  # Tool schemas
│       │   ├── 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 structs
│           ├── ImageExport.swift      # PHImageManager, base64 JPEG
│           ├── PhotosAccess.swift     # Library authorization
│           ├── DateParsing.swift      # ISO 8601 date parsing
│           ├── GeoUtils.swift         # Haversine distance for location search
│           └── ContentClassifier.swift # Vision ML keyword matching
└── README.md

Notes

• list_moments returns an empty list on macOS; the fetchMoments API is iOS - only.
• Keyword search in search_photos uses Vision ML (pizza, food, car, city, dog, beach, etc.). It analyzes up to 1000 photos—combine with date range for large libraries.
• Place search via get_photos_by_place—geocodes "Valencia", "Paris" etc. and finds photos taken there.
• Date search accepts yyyy - MM - dd or full ISO 8601. Use start_date and end_date for ranges.

📄 License

MIT