photos-macos

PhotosMCP is a read-only MCP server written in Swift that exposes your macOS Photos library to AI assistants via the MCP protocol. It provides a set of tools that let clients query albums, search your library, retrieve asset metadata and images, and perform location/date/place based queries. The server uses PhotoKit under the hood, so it requires that the Photos app has a library available and that the server process has permission to access Photos. Tools include listing albums, getting library statistics, performing keyword and geolocation searches, and exporting image data as base64-encoded thumbnails or full-resolution images. You can call these tools through the MCP protocol to integrate with chat assistants, automation scripts, or other AI workflows. All tools respect the server’s read-only stance and will return clear errors if access is denied or if a requested asset cannot be read.

Prerequisites:

• macOS 13.0+
• Xcode 14+ and Swift 6.0+ support (Swift toolchain via Xcode)
• A Photos library configured in the Photos app

1. Clone the repository: git clone https://github.com/your-org/photos-macos-mcp.git cd photos-macos-mcp

2. Build the project in release mode: swift build -c release

3. Locate the built executable: .build/release/PhotosMCP

4. Run the server (in the repo root or from wherever the binary resides): ./build/release/PhotosMCP The server starts and listens for MCP requests via the standard MCP transport.

5. (Optional) Integrate with Claude Desktop or other MCP clients:

   • Use an MCP client config pointing to the PhotosMCP binary path, for example: { "mcpServers": { "photos": { "command": "/absolute/path/to/.build/release/PhotosMCP", "args": [] } } }

Prerequisite notes:

• The first run may prompt for Photos access. You must grant permission in System Settings → Privacy & Security → Photos.
• This server is read-only and will not modify or delete any photos or albums.

Tips and common issues:

• Permissions: On first launch, the system may prompt for Photos access. Without permission, all tools will fail with a descriptive error.
• Privacy: Place-based searches may send location tokens to Apple’s geocoding services. Ensure you understand the data flow when enabling geolocation-based queries.
• Exports: Thumbnails and full images are written to a PhotosMCP subdirectory in the system temp folder; files older than 1 hour are cleaned up automatically when new exports occur.
• Read-only: The server only reads from PhotoKit; it does not modify any assets or album structures.
• If you see empty results for moments on macOS, note that list_moments returns an empty list due to iOS-only fetchMoments behavior on macOS.
• For large libraries, use limit and offset parameters on list/search tools to paginate results (default limit is 50, max 200).