Verified

Apple Photos MCP Server

macOS Photos library interface for querying, searching, and exporting image data.

Data last scanned today · Reviewed today

5522 tools★ 20JavaScriptMIT

Overview

This server bridges AI assistants with the macOS Apple Photos library, leveraging the osxphotos library to provide deep inspection capabilities. Users can search their collection by metadata, view thumbnails directly in their AI interface, identify duplicates, and retrieve detailed EXIF data for specific images. The server operates as read-only by default to ensure library safety. For advanced users who require more control, an opt-in write mode can be activated via environment variable, allowing the assistant to organize photos into albums, update titles, assign tags, or modify favorite status without ever deleting files.

Our verdict

With a security score of 35/100, this tool is categorized as high risk. Because the project is community-maintained and has not yet undergone editorial review, users should exercise caution, particularly regarding the opt-in write tools. It is best suited for power users who are comfortable managing their own library risks and verify the active source code before enabling write permissions.

Supports read-only access to protect library integrity.
Provides direct thumbnail retrieval for image identification.
Contains only two direct dependencies reducing supply-chain surface.
Includes documented opt-in features for metadata management.

Lacks an official vendor maintenance status.
Authentication and read-only implementation are not yet reviewed.

Setup

Claude Desktop

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

Paste into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart Claude Desktop. Some servers require API keys or tokens as environment variables — check the project's README and add an "env" object if needed.

No read-only mode — running this grants full read/write access.
No built-in authentication — anyone with access to this config can invoke every tool it exposes.

Tools

Tool	Description	Risk
health-check	Verify osxphotos is installed and the Photos library can be opened.	low
doctor	Run a full setup diagnostic — six checks: the resolved Python interpreter, osxphotos installation, sidecar mode, the write-tools gate, Photos library readability, and Full Disk Access.	low
library-info	High-level stats about the Photos library.	low
query	Search the library with combinable filters.	low
get-photos	Fetches full metadata for up to 50 UUIDs in one call.	low
get-selected-photos	Returns the photos currently selected in the Photos.app window.	low
get-thumbnail	Returns a photo as an inline viewable image from Photos' pre-generated derivatives.	low
find-duplicates	Groups exact duplicates using Photos' own fingerprint detection.	low
list-albums	All albums with their folder paths and photo counts.	low
list-folders	All folders with parent and album/subfolder counts.	low

Compatibility

Client	Local	Docker	Remote	Read-only
ChatGPT
Claude Desktop
Cursor
VS Code
Windsurf

Frequently asked questions

›Is my Apple Photos library modified when I use this server?

The server is read-only by default, ensuring your library is never modified. Write operations are only enabled if you explicitly set the environment variable APPLE_PHOTOS_MCP_ENABLE_WRITES=1.

›What are the system requirements for running this server?

The server requires macOS and necessitates that you grant Full Disk Access to the host application (such as Terminal, VS Code, or Claude Desktop). Additionally, Python 3.11+ must be installed on your system PATH.

›Does the server perform any destructive write actions?

No. The opt-in write tools allow you to modify metadata like titles, descriptions, keywords, favorites, and dates, or manage albums, but the server never performs any deletion actions.

›What happens during the first tool call after installation?

The server automatically bootstraps a Python virtual environment with the necessary osxphotos dependency. This one-time setup process typically takes about a minute to complete.

›How is my data handled?

All data processing occurs locally on your machine. The server reads your Apple Photos library SQLite database directly, and no data is transmitted to external services.