Open a Google Photos picker so the user can choose photos and videos from their ENTIRE library. This is the only way to reach media this app did not upload itself; the Library API cannot see anything else.

Returns a picker_uri. Give that URL to the user and stop. They open it, select items in Google Photos, and finish. Then call check_pick_session until ready is true, and list_picked_media to see what they chose.

Do not call list_picked_media straight after this. Nothing has been picked yet and the empty result does not mean the library is empty.

Poll a picker session started by start_pick_session. ready is true once the user has confirmed a selection.

Respect the poll_interval_seconds from start_pick_session rather than polling in a tight loop. If it is still false after a few minutes, the user has probably not opened the link yet; ask them rather than polling forever.

Return the media items the user selected in a picker session. Call check_pick_session first; this returns an empty list until the selection is confirmed.

The items include a base_url that expires in about an hour. To get actual bytes, pass an item's base_url to download_picked rather than handing the URL to the user.

Fetch the bytes of an item the user picked, returned as base64 with its mime type. Pass the item's base_url from list_picked_media.

Use this rather than giving a base_url to the user or to another tool: the URL needs an auth header and a size suffix, and it expires within the hour. Large files are refused; raise max_mb only when the caller genuinely needs the original.

Create a new, empty album in the user's Google Photos. It is private, and it belongs to this app, which is what makes it editable later. Add items with add_to_album or by passing album_id when uploading.

List the albums this app created, newest first. Only albums created by this app are listed. Albums the user made in the Google Photos app are not visible to any scope available since 2025-04-01.

Pass next_page_token from a previous result to continue; a library with many albums will not fit in one page.

Fetch a single album by id, including its item count, cover photo and sharing state.

A 404 here usually means the album exists but was not created by this app, rather than that the id is wrong. Only albums created by this app are listed. Albums the user made in the Google Photos app are not visible to any scope available since 2025-04-01.

Change an album's title, its cover photo, or both. The cover has to be a media item that is already in the album; setting one that is not returns an error.

Turn an album into a shared album and return a link anyone can open without signing in.

This is the one thing here that reaches people outside the account, and a link that has been sent cannot be recalled. unshare_album revokes it, but not from anyone who already saved the contents. Requires confirm: true.

Revoke an album's share link and make it private again. Anyone who already opened the link loses access, but anything they saved or downloaded stays with them.

List the shared albums this app created, with their share links. Only albums created by this app are listed. Albums the user made in the Google Photos app are not visible to any scope available since 2025-04-01.

Add media items this app created to an album this app created. Both sides have to be app-created; a picked item cannot be added directly, it has to be uploaded into the library first with save_to_library.

Up to 50 items per call.

Take media items out of an album. The items stay in the user's library; only the album membership goes. Up to 50 per call.

Insert an enrichment into an album: a text caption, a named location, or a map between two places. Enrichments sit between photos and are how an album reads as a story rather than a grid.

Position defaults to the end of the album.

List media items, newest first, optionally scoped to one album. Only media uploaded by this app is returned. To reach anything else in the user's library, use start_pick_session.

Pass next_page_token to continue past the first page.

Filter media by date range, content category, media type or favourites. Only media uploaded by this app is returned. To reach anything else in the user's library, use start_pick_session.

There is no free-text search in the Google Photos API: you cannot search for "beach" as a word. Categories are the closest equivalent, and they are Google's own classifier, not tags the user set. Call describe_filter_capabilities for the exact values.

An album_id cannot be combined with any filter; Google rejects that combination.

Return the exact content categories, media types and feature filters search_library accepts, plus what the Google Photos API cannot do. Costs no API call and no quota.

Read this before guessing a category name. A wrong one is rejected rather than ignored.

Fetch a single media item by id, with its dimensions, creation time and description. Only media uploaded by this app is returned. To reach anything else in the user's library, use start_pick_session.

Fetch up to 50 media items by id in one call. Prefer this over repeated get_media_item: it is one request against the daily quota rather than fifty. Only media uploaded by this app is returned. To reach anything else in the user's library, use start_pick_session.

Ids that cannot be read come back in failed with a reason, rather than failing the whole call.

Write the description shown under a photo or video in Google Photos. Only works on media this app uploaded. Passing an empty string clears it.

Fetch the bytes of a media item this app uploaded, returned as base64 with its mime type. Resolves the item's current base_url first, so it works with a plain id and never with a stale URL.

Download files from public URLs and add them to the user's Google Photos, optionally straight into an album.

There is no API to delete a media item once uploaded, so this cannot be undone here: the user would have to remove it by hand in the Google Photos app. Requires confirm: true.

Up to 20 URLs per call.

Upload a photo or video from a path on the machine running this server, optionally straight into an album.

There is no API to delete a media item once uploaded. Requires confirm: true.

Take items the user chose in a picker session and upload them as app-created media, so the other tools can then read, describe and organise them.

This is the bridge between the two halves of the API. A picked item is readable only for the life of its session; once saved it is a normal media item this app owns. It does create a second copy in the user's library. Requires confirm: true.

Pass base_urls from list_picked_media, up to 20.

Create an album and upload files into it in a single step. Saves three round trips over create_album, upload_from_url and add_to_album, and leaves no empty album behind if the uploads fail.

There is no API to delete uploaded media. Requires confirm: true. Up to 20 URLs.

Show every Google account this server can act as, and which one acts when a tool names none.

Pass one of these names as account on any tool to act as that library instead of the default. Costs no API call.

Report whether the server can reach Google Photos, which account it acts as, and which scopes the grant actually carries.

Call this first when anything returns a permission error. A missing scope and a revoked token produce similar-looking failures and are fixed differently.

Report how much of the Google Cloud project's daily budget this server has spent: 10,000 API requests and 75,000 media-byte requests, both resetting at midnight UTC.

Counted by this process since it started, so it is a floor rather than a true reading. Worth checking before a long batch, and worth reading when calls start failing with RESOURCE_EXHAUSTED.

Escape hatch for an endpoint this server does not wrap. Give a path relative to the API root and it is sent with the current access token.

Prefer a named tool where one exists: they shape the response, handle pagination and explain their errors. Reach for this when the API has something the tools do not cover yet.