Search and organize Apple Photos with OwAI

Connect the System Photo Library on your Mac

Apple Photos connects through PhotoKit on macOS 11 or later. Install a current OwAI desktop build that includes this native integration. The Apple Photos button does not appear on Windows or Linux. Updating a website or refreshing an old desktop interface does not install the native connector.

Choose the entire System Photo Library or one Photos album. This uses the system library selected in Photos, not an arbitrary .photoslibrary package and not a direct iCloud web login. An album limits source membership. Editable native user albums link to OwAI collections, and favorites synchronize in both directions. Group rules and people labels stay in OwAI.

1. Open Apple Photos on the OwAI home page, then select Allow Photos access. Permission is requested only after this action.
2. Grant full Photos access. Limited access is not supported. If necessary, change System Settings → Privacy & Security → Photos, then select Check access. Older macOS versions use System Preferences → Security & Privacy → Privacy → Photos.
3. Choose System Photo Library or an album, optionally name the source and enable Detect faces, then select Add Photos source.
4. Choose search, Media indexing and Face detection in App Settings and let the shared queue finish. These are the same inference settings as local folders; there is no separate Photos inference mode.

• Apple Photos features
• Download OwAI

iCloud downloads, formats and cache

OwAI reads library metadata and requests media when indexing, viewing or an assistant needs it. Uncached iCloud items require internet access. Initial indexing can download substantial data; the owning Mac must stay available even when hosted inference is selected. OwAI does not keep a permanent second copy of the whole library.

PhotoKit supplies the current rendered image or video, including supported edits in Photos. OwAI uses JPEG images and MP4 videos for compatible processing and viewing. These are rendered copies, not byte-for-byte original HEIC, RAW or MOV files. Original filenames and capture metadata remain useful catalog information; a filename extension does not describe the cached rendition’s format.

The managed cache targets 5 GiB. Least-recently-used entries can be removed, while active viewers and decoders hold leases that protect their files. A single resource must fit the limit; if active files fill the cache, close viewers and retry. Temporary downloads need additional disk space. Cached access still requires Photos permission.

Ordinary images and videos are indexed through the existing media pipeline. Live Photos currently contribute their still image; the paired motion clip is not separately searchable. Hidden media is excluded. Video search uses sampled frames, not every frame or a speech transcript.

Changes made in Photos

Sync now in the Apple Photos dialog or the source’s refresh button requests a scan. While OwAI is running, periodic metadata scans run approximately every five minutes. Queue activity, large inventories, downloads and errors can delay completion; there is no instant Photos change observer.

A completed scan discovers media edits, additions and album membership changes. Detected content revisions are processed again. Items absent from a complete source inventory are removed from OwAI’s index. Permission failures or incomplete scans do not prove that originals were deleted. Removing the source from OwAI leaves the Photos library intact.

Sync native albums and favorites without rewriting media

Editable regular user albums import as linked OwAI collections, including empty albums. Creating a collection, editing its membership or deleting it updates the native Photos album. Rename an album in Photos; its title imports on scan. OwAI currently has no collection-rename command. Confirmed native album disappearance removes its linked collection unless unresolved local intent remains. An existing album keeps its link even when no members are in source scope. Smart albums, shared albums and synced read-only albums are not writable collection targets. Membership edits from an album-scoped source preserve native members outside that source.

OwAI groups publish their names and computed image membership to linked Photos albums; renaming an OwAI group updates its album title. Search and date rules remain in OwAI, not Photos smart albums. Publication is outbound-only: native title or membership edits do not change the OwAI group, and its next change republishes the computed state. A missing native group album is unlinked without deleting its OwAI rules. Collections and favorites synchronize both ways; unresolved local changes take precedence until native sync is resolved.

Deleting a linked collection or group requests album-container deletion, never original deletion. Native deletion is refused if the album contains members outside the source, including hidden or unindexed assets. A local deletion can already be saved while native sync needs attention; the Photos album remains. Removing an album member is also different from deleting its original.

The Apple Photos dialog shows pending and failed organization changes. Sync now requests reconciliation and retries safe writes. Keep the owning Mac online with full Photos access; a queued change is not confirmation that its native album or favorite update completed. MCP results expose native_sync with applied, pending or failed status and per-operation errors; local and remote assistants can check get_library_command. Do not blindly repeat an unconfirmed album creation. Changes can propagate through iCloud Photos. People labels and duplicate-distinct decisions remain OwAI-only.

For a pending organization command, poll its existing command ID. For a failed native_sync, resolve the error and use Sync now, then repeat the same tool request with the same idempotency_key. This rechecks the saved native receipt without repeating the OwAI change; remote retries keep the same command ID. Do not create a new album request to retry an unconfirmed one. Unrelated failures are not automatically retried.

Photos originals cannot be optimized, overwritten, renamed as files or moved by changing their source path. Exports, watermarks and Reimagine produce separate outputs rather than replacing originals. The source’s downloaded JPEG or MP4 is a rendered copy, not an archival export of the untouched original.

Reviewed deletion uses Photos Recently Deleted

Deleting an original is a separate, explicitly approved operation. Preview the exact assets, filenames and favorites with preview_media_deletion, then obtain approval for that plan before apply_media_deletion. The plan identifies operation photos_recently_deleted and recovery_provider apple_photos. Favorite protection includes both OwAI and Photos favorites across all indexed aliases of the same native asset; specifically approve any favorites included.

PhotoKit deletion removes the asset from the System Photo Library and all Photos albums, not only the selected source or album. iCloud Photos may propagate deletion to other devices. It uses Apple’s Recently Deleted recovery and retention, not OwAI’s local 30-day purge. OwAI does not permanently purge these Photos assets or promise immediate disk-space savings.

Restore in Photos → Recently Deleted, then sync Apple Photos in OwAI. The next successful scan imports recovered media and its current native album/favorite state, but does not reconstruct prior OwAI-only metadata, people labels or index identity. Existing group rules remain; recovery does not recreate deleted rules. Do not assume Photos Recover preserves every former album membership or favorite; check Photos after recovery. The integration does not provide programmatic Photos restoration through restore_media. A pending or unconfirmed deletion is not success: inspect the completed command result, check Photos and sync before retrying. Changed media or favorites require a fresh reviewed plan.

• Preview, approval and completion workflow

Use Apple Photos and OneDrive through the same MCP tools

Both local and remote MCP require Cloud Access. Discover real source IDs and source kinds with inspect_library; keep each search or management operation scoped to the intended source. Use search_media, read_media, inspect_duplicates and the normal collection, group and people tools advertised by the connected schema. There is no separate Apple Photos MCP connector.

Local MCP reads through the running OwAI app and follows App Settings. Remote MCP searches the last synced index, so it can return metadata while the Mac is offline. To make Photos metadata searchable remotely, enable Cloud index sync and wait for initial sync. The index server must also run a version accepting PhotoKit capture metadata.

Remote Photos image and video-still reads require the owning Mac online with OwAI running, full Photos authorization and Remote media access enabled. Remote media access defaults off and is separate from cloud index sync or hosted inference. Photos mutations, including approved deletion, execute on the owning Mac. Keep command IDs and inspect get_library_command until completion; a queued command is not a completed change.

OneDrive is different: its shared catalog edits and supported provider operations run on the server, and read_media can retrieve original images or video stills without an online desktop or desktop relay. Fully cloud-based OneDrive indexing can continue while the desktop is off. A Photos source is never converted into that server-owned OneDrive model.

read_media uses the full current Photos image at its available rendered dimensions when it fits the 5 MiB inline response limit, adapting it only when required to fit. It never substitutes a gallery thumbnail. PhotoKit’s JPEG rendition is reported as adapted_image rather than an untouched original; a video frame is reported as video_still. OneDrive starts from the original image and adapts oversized or incompatible images to the largest practical uncropped rendition. Display depends on the assistant’s support for MCP image output. open_media is a separate same-computer window action, not remote control or proof that bytes reached the conversation.

• Connect AI assistants
• OneDrive setup and MCP guide
• Local and remote MCP

Why Apple Photos still needs your Mac

Apple documents PhotoKit for access to a person's Photos library, including iCloud media, through an authorized Apple device. It does not document a supported public server API for personal iCloud Photos comparable to Microsoft Graph for OneDrive. OwAI therefore keeps the owning Mac as its Photos bridge, including for album and favorite changes.

CloudKit web services access an app's own containers and databases; they do not grant access to Apple's Photos library. OwAI does not ask for your Apple Account password or use private iCloud website endpoints. Cloud index search can use already-synced metadata while the Mac is offline, but fresh Photos media and native changes still need that Mac.

• Apple's PhotoKit overview
• Apple's CloudKit container model

Check access and completed indexing first

If the button is missing, verify macOS support and the installed desktop build. If no media appears, check full Photos authorization, the system library, selected album, hidden status and completed indexing. For an iCloud download failure, reconnect to the internet and refresh.