apple-photos

Apple Photos MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to query and export from the macOS Apple Photos library, backed by the osxphotos library.

Read-only against the Photos library. Exports write files to a directory you choose, but the library itself is never modified.

What is This?

This server acts as a bridge between AI assistants and Apple Photos. Once configured, you can ask Claude (or any MCP-compatible AI) to:

• "Find all my photos from our trip to Spain in 2023"
• "Show me my favorite sunset photos"
• "How many photos do I have? What are my top keywords?"
• "Find photos of Sarah from last summer and export them to ~/Desktop/sarah-summer"
• "List my albums"
• "Tell me everything about photo UUID ABC-123"

The AI assistant communicates with this server, which uses osxphotos to read the Photos library SQLite database directly. All data stays local on your machine.

Quick Start

Using Claude Code (Easiest)

If you're using Claude Code (in Terminal or VS Code), just ask Claude to install it:

Install the sweetrb/apple-photos-mcp MCP server so you can help me query my Apple Photos library

Claude will handle the installation and configuration automatically. After install, you'll need to install osxphotos (Python) and grant Full Disk Access — see Requirements below.

Using the Plugin Marketplace

Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:

/plugin marketplace add sweetrb/apple-photos-mcp
/plugin install apple-photos

This method also installs a skill that teaches Claude when and how to use Apple Photos effectively.

Manual Installation

1. Install the server:

npm install -g github:sweetrb/apple-photos-mcp

2. Install osxphotos (the Python library this server depends on):

pip3 install osxphotos

Or, if you cloned the repo, run npm run setup to create a project-local Python venv with osxphotos pre-installed.

3. Add to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-photos": {
      "command": "npx",
      "args": ["apple-photos-mcp"]
    }
  }
}

4. Grant Full Disk Access to the app hosting the MCP server (Claude Desktop, Terminal, VS Code, etc.) — see Full Disk Access below.

5. Restart Claude Desktop and start using natural language:

"How many photos are in my library?"

Requirements

• macOS - The Photos library is macOS-only
• Node.js 20+ - Required for the MCP server
• Python 3.9+ with osxphotos - The server uses osxphotos under the hood. Install via pip3 install osxphotos or via npm run setup if installing from source.
• Apple Photos - Must have a Photos library (default location: ~/Pictures/Photos Library.photoslibrary)
• Full Disk Access - The Photos library lives in a protected directory. The host app needs Full Disk Access — see below.

Features

Querying

Feature	Description
Library Stats	Total counts of photos, movies, albums, folders, keywords, persons
Query	Search by date range, album, keyword, person, favorite/hidden flags, photo/movie type, title/description substring
Photo Details	Full metadata for one photo: dimensions, location, place, EXIF-derived flags (HDR, live, portrait, panorama, raw, edited, etc.)
List Albums	All albums with their folder paths and photo counts
List Folders	All folders with parent and album/subfolder counts
List Keywords	Keywords sorted by usage count
List Persons	People detected by Photos face recognition, sorted by photo count

Export

Feature	Description
Export Originals	Copy original photos to a destination directory
Export Edited	Copy the edited version instead of the original
Live Photos	Optionally include the live-photo video alongside the still
Raw Files	Optionally include the raw (NEF, CR2, etc.) sidecar
Multi-photo Export	Export multiple UUIDs in a single call
Auto iCloud Download	If an original isn't on disk, export falls back to Photos.app to download it on demand — no extra parameter needed

Diagnostics