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

| Feature | Description | |---------|-------------| | Health Check | Verify osxphotos is installed and the library can be opened |

Tool Reference

This section documents all available tools. AI agents should use these tool names and parameters exactly as specified.

Discovery

health-check

Verify osxphotos is installed and the Photos library can be opened.

Parameters: None

Returns: osxphotos version, library path, and total photo count — or an error if the library is inaccessible.

library-info

High-level stats about the Photos library.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | library | string | No | Path to a non-default .photoslibrary (defaults to system library) |

Returns: Library path, Photos DB version, Photos.app version, counts of photos / movies / albums / folders / keywords / persons.

Query

query

Search the library with combinable filters. Returns photo summaries with UUIDs — use get-photo for full details on a specific match.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | uuid | string[] | No | Specific UUIDs to fetch | | album | string[] | No | Album name(s); ANY-match | | keyword | string[] | No | Keyword(s); ANY-match | | person | string[] | No | Person name(s); ANY-match | | fromDate | string | No | ISO 8601 lower bound on photo date (e.g. "2025-06-01") | | toDate | string | No | ISO 8601 upper bound on photo date | | favorite | boolean | No | Only favorites | | notFavorite | boolean | No | Exclude favorites | | hidden | boolean | No | Only hidden photos | | notHidden | boolean | No | Exclude hidden photos (default behavior) | | photos | boolean | No | Include still photos | | movies | boolean | No | Include movies | | title | string | No | Substring match on title | | description | string | No | Substring match on description | | limit | number | No | Cap the number of results | | library | string | No | Path to a non-default .photoslibrary |

Example - Recent favorites of Sarah:

{
  "person": ["Sarah"],
  "favorite": true,
  "fromDate": "2025-06-01",
  "limit": 50
}

Example - Sunset keyword across two albums:

{
  "keyword": ["sunset"],
  "album": ["Vacation 2024", "Beach Trips"]
}

Returns: Photo summaries (UUID, filename, date, dimensions, favorite/hidden flags, albums, keywords, persons).

get-photo

Get full metadata for a single photo by UUID.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | uuid | string | Yes | Photo UUID | | library | string | No | Path to a non-default .photoslibrary |

Example:

{
  "uuid": "33AC0410-D367-43AE-A839-12C7EF482020"
}

Returns: All metadata for the photo: dimensions, original dimensions, dates (taken/added/modified), title, description, location (lat/lon), place (name/country), albums, keywords, persons, labels, type flags (HDR / live / raw / edited / portrait / panorama / selfie / screenshot / slow-mo / time-lapse / burst), file paths (original, edited, raw, live-photo video), file size, UTI.

Browse

list-albums

List all albums in the library.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | library | string | No | Path to a non-default .photoslibrary |

Returns: Each album's title, folder path, photo count, shared status, and UUID.

list-folders

List all folders in the library.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | library | string | No | Path to a non-default .photoslibrary |

Returns: Each folder's title, parent folder, album count, and subfolder count.

list-keywords

List keywords sorted by usage count.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | limit | number | No | Cap to top-N keywords | | library | string | No | Path to a non-default .photoslibrary |

Returns: Keywords with their photo counts, sorted descending.

list-persons

List people detected by Photos face recognition, sorted by photo count.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | limit | number | No | Cap to top-N persons | | library | string | No | Path to a non-default .photoslibrary |

Returns: Persons with their photo counts, sorted descending. Unidentified faces appear as _UNKNOWN_.

Export

export

Export one or more photos by UUID to a destination directory.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | uuid | string[] | Yes | Photo UUID(s) to export (non-empty) | | dest | string | Yes | Destination directory (created if missing) | | edited | boolean | No | Export the edited version instead of the original | | live | boolean | No | Also export the live-photo video | | raw | boolean | No | Also export the raw image | | overwrite | boolean | No | Overwrite existing files at the destination | | library | string | No | Path to a non-default .photoslibrary |

Example - Originals to a folder:

{
  "uuid": ["33AC0410-...", "EEFCEF1D-..."],
  "dest": "~/Desktop/exports"
}

Example - Edited versions plus raw and live-photo video:

{
  "uuid": ["33AC0410-..."],
  "dest": "~/Desktop/exports",
  "edited": true,
  "raw": true,
  "live": true,
  "overwrite": true
}

Returns: Destination path, count of files exported, count skipped, list of exported file paths, and any errors per UUID.

iCloud-only originals: If a photo's original isn't on disk (Photos is using "Optimize Mac Storage"), the export automatically falls back to Photos.app via AppleScript, which downloads the original on demand — same behavior as opening the photo in Photos. This is slower than a direct file copy; expect waits proportional to download size for large batches. Photos that genuinely can't be exported (e.g. edited=true requested but no edits exist) are still skipped with a per-UUID reason.

Usage Patterns

Basic Workflow

User: "How many photos do I have?"
AI: [calls library-info]
    "You have 30,968 items: 30,435 photos and 533 movies across 46 albums..."

User: "Find my favorite sunset photos"
AI: [calls query with keyword=["sunset"], favorite=true]
    "Found 12 favorite sunset photos. Here are the most recent..."

User: "Tell me about the first one"
AI: [calls get-photo with uuid="..."]
    "Taken on 2025-09-14 at 19:47, in Big Sur..."

Two-step: Query then Export

User: "Export all photos of Mollee from the beach to ~/Desktop/mollee-beach"
AI: [calls query with person=["Mollee"], keyword=["beach"]]
    "Found 109 photos."
AI: [calls export with the UUIDs and dest="~/Desktop/mollee-beach"]
    "Exported 109 files to ~/Desktop/mollee-beach."

Browsing Library Structure

User: "What are my top 10 keywords?"
AI: [calls list-keywords with limit=10]
    "Photo Stream (1561), Mollee (109), beach (109), 2015 Feb Keweenaw..."

User: "Who appears most in my photos?"
AI: [calls list-persons with limit=10]
    "Rita Sweet (29), Robert B Sweet (28), Jennifer Sweet (24)..."

Targeting a Different Library

By default, all operations use the system Photos library. To work with a different .photoslibrary:

User: "Show albums in my old archive at /Volumes/Archive/Photos.photoslibrary"
AI: [calls list-albums with library="/Volumes/Archive/Photos.photoslibrary"]
    "32 albums in the archive..."

Installation Options

npm (Recommended)

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

From Source (with Project-Local venv)

git clone https://github.com/sweetrb/apple-photos-mcp.git
cd apple-photos-mcp
npm install
npm run setup    # creates ./venv and installs osxphotos
npm run build

If installed from source, use this configuration:

{
  "mcpServers": {
    "apple-photos": {
      "command": "node",
      "args": ["/path/to/apple-photos-mcp/build/index.js"]
    }
  }
}

The server prefers a project-local venv at ./venv/bin/python3 if present, and otherwise falls back to system python3. This means a global npm install works as long as osxphotos is on the system Python.

Full Disk Access

The Photos library SQLite database lives in a protected directory (~/Pictures/Photos Library.photoslibrary/database/). osxphotos reads this database directly — it does not go through Photos.app — so the host process needs Full Disk Access.

How to Grant Full Disk Access

1. Open System Settings (or System Preferences on older macOS)
2. Go to Privacy & Security > Full Disk Access
3. Click the + button
4. Add the application that hosts the MCP server:
   • Claude Desktop: Add /Applications/Claude.app
   • Terminal: Add /Applications/Utilities/Terminal.app
   • VS Code: Add /Applications/Visual Studio Code.app
   • iTerm: Add /Applications/iTerm.app
5. Restart the application after granting access

Without Full Disk Access

The health-check tool will fail and report a permissions error. No tool will be able to open the library.

Architecture

This package is a TypeScript MCP server with a Python sidecar:

• The MCP server (Node) speaks the Model Context Protocol over stdio.
• A bundled Python script (src/utils/photos_reader.py) uses osxphotos to read the Photos library and returns JSON.
• The TypeScript side spawns the Python script via child_process.execFileSync.

This is the same pattern used by apple-numbers-mcp for the numbers-parser Python library.

Security and Privacy

• Local only — All operations happen locally via osxphotos. No data is sent to external servers.
• Read-only against the Photos library — the library is never modified.
• Exports write to disk — export writes files to the destination directory you specify. Confirm destinations before running on shared machines.
• No credential storage — The server doesn't store any passwords or authentication tokens.

Known Limitations

| Limitation | Reason | |------------|--------| | macOS only | Apple Photos and osxphotos are macOS-specific | | Read-only | osxphotos reads the Photos library; this server does not modify it | | Full Disk Access required | The Photos library SQLite database is in a protected directory | | iCloud-only export is slower | Originals that aren't on disk are downloaded on demand via Photos.app/AppleScript. The export still succeeds, but takes longer than a local copy and requires Photos.app to be installed and signed in to iCloud | | Photos.app may lock the library | If Photos.app is mid-write, opening the library can fail; close Photos.app and retry | | Person filter requires named faces | osxphotos cannot filter by unnamed/unrecognized faces |

Troubleshooting

"osxphotos not installed. Run: npm run setup"

• Run pip3 install osxphotos (global install) or npm run setup (project-local venv).
• If you used a virtualenv, make sure it's the one at ./venv/ in the project directory.

"Library not found" or permission errors

• Grant Full Disk Access to the host app — see Full Disk Access.
• Verify the library path: default is ~/Pictures/Photos Library.photoslibrary.

Photo not found / "Photo not found: "

• The UUID may be wrong — re-run query to get current UUIDs.
• The photo may have been deleted from the library.

Exports skip files with "missing"

• Since 0.1.3, the export auto-downloads iCloud-only originals via Photos.app, so this skip should be rare. If it still happens:
  • "original not downloaded from iCloud (download attempt returned no files)" — Photos.app couldn't fetch it. Check iCloud connectivity, that you're signed in, and that the photo isn't excluded by a Photos sync setting.
  • "no edited version exists" / "no raw sidecar exists" — edited=true or raw=true was requested but the photo doesn't have one. Retry without that flag.

Photos.app errors when running

• Closing Photos.app may resolve database-lock errors. osxphotos opens the library in read-only mode but still requires that no writer holds an exclusive lock.

Development

npm install         # Install dependencies
npm run setup       # Create ./venv with osxphotos
npm run build       # Compile TypeScript
npm test            # Run unit tests
npm run typecheck   # Type-check without emitting
npm run lint        # Check code style
npm run format      # Format code

The Python sidecar is a thin CLI that the TypeScript layer shells out to:

./venv/bin/python3 src/utils/photos_reader.py library-info
./venv/bin/python3 src/utils/photos_reader.py query --keyword sunset --limit 5
./venv/bin/python3 src/utils/photos_reader.py export --uuid <uuid> --dest /tmp/out

Author

Rob Sweet - President, Superior Technologies Research

A software consulting, contracting, and development company.

• Email: [email protected]
• GitHub: @sweetrb

License

MIT License - see LICENSE for details. This project is not affiliated with Apple Inc. or the osxphotos project.

Contributing

Contributions are welcome! Please open an issue or PR at github.com/sweetrb/apple-photos-mcp.

Related Projects

• apple-mail-mcp — MCP server for Apple Mail
• apple-notes-mcp — MCP server for Apple Notes
• apple-numbers-mcp — MCP server for Apple Numbers spreadsheets
• osxphotos — The Python library that powers this server