google-photos-mcp-cliBLOCK
Google Photos MCP server and CLI for Claude Code, Codex and AI agents. 26 tools for the photo picker, uploads, albums, enrichments, descriptions and app-created media.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://www.npmjs.com/package/@thenavidm/google-photos-mcp-cli) [](./LICENSE) [](https://github.com/thenavidm/google-photos-mcp-cli/actions) [](https://youtube.com/@thenavidm?sub_confirmation=1) [](https://x.com/thenavidm) [](https://linkedin.com/in/thenavidm)
Google Photos MCP server and CLI for Claude Code, Codex and AI agents. 26 tools for the photo picker, uploads, albums, enrichments, descriptions and app-created media.
One install gives you both surfaces, the same tools under the same names.
It opens Google's own picker, so you choose exactly what the agent sees. It uploads photos and videos, builds albums, writes captions, and adds the enrichments that make an album read as a story.
Google removed whole-library read access for every third-party app on 31 March
- Asking you to choose is the only route left, so this is built around the
picker rather than pretending otherwise.
Connect as many Google accounts as you need.
Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI.
20f37801e3eeOBSERVED · 2026-10-11Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add google-photos-mcp-cli --env GOOGLE_PHOTOS_CLIENT_SECRET=${GOOGLE_PHOTOS_CLIENT_SECRET} --env GOOGLE_PHOTOS_REFRESH_TOKEN=${GOOGLE_PHOTOS_REFRESH_TOKEN} -- npx -y @thenavidm/[email protected]{
"mcpServers": {
"google-photos-mcp-cli": {
"command": "npx",
"args": [
"-y",
"@thenavidm/[email protected]"
],
"env": {
"GOOGLE_PHOTOS_CLIENT_SECRET": "${GOOGLE_PHOTOS_CLIENT_SECRET}",
"GOOGLE_PHOTOS_REFRESH_TOKEN": "${GOOGLE_PHOTOS_REFRESH_TOKEN}"
}
}
}
}Exposed tools (26)
16 read · 9 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
add_album_enrichment | write | 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.\n\nPosition defaults to the end of the album. |
add_to_album | write | 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.\n\nUp to 50 items per call. |
auth_status | read | Report whether the server can reach Google Photos, which account it acts as, and which scopes the grant actually carries.\n\nCall this first when anything returns a permission error. A missing scope and a revoked token produce similar-looking failures and are fixed differently. |
build-album | write | Create an album from a set of image URLs |
check_pick_session | read | Poll a picker session started by start_pick_session. |
create_album | write | Create a new, empty album in the user |
create_album_with_media | write | 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.\n\nThere is no API to delete uploaded media. Requires confirm: true. Up to 20 URLs. |
describe_filter_capabilities | read | 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.\n\nRead this before guessing a category name. A wrong one is rejected rather than ignored. |
diagnose | read | Work out why Google Photos is not responding |
download_media_item | read | Fetch the bytes of a media item this app uploaded, returned as base64 with its mime type. Resolves the item |
download_picked | read | Fetch the bytes of an item the user picked, returned as base64 with its mime type. Pass the item |
get_album | read | Fetch a single album by id, including its item count and cover photo.\n\nA 404 here usually means the album exists but was not created by this app, rather than that the id is wrong. ${APP_CREATED_NOTE} |
get_media_item | read | Fetch a single media item by id, with its dimensions, creation time and description. ${APP_CREATED_NOTE} |
get_media_items | read | 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. ${APP_CREATED_NOTE}\n\nIds that cannot be read come back in \ |
list_accounts | read | Show every Google account this server can act as, and which one acts when a tool names none.\n\nPass one of these names as |
list_albums | read | List the albums this app created, newest first. ${APP_CREATED_NOTE}\n\nPass next_page_token from a previous result to continue; a library with many albums will not fit in one page. |
list_app_media | read | List media items, newest first, optionally scoped to one album. ${APP_CREATED_NOTE}\n\nPass next_page_token to continue past the first page. |
list_picked_media | read | 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.\n\nThe items include a |
pick-and-work | read | Have the user choose photos, then do something with them |
quota_status | read | Report how much of the Google Cloud project |
remove_from_album | destructive | Take media items out of an album. The items stay in the user |
search_library | read | Filter media by date range, content category, media type or favourites. ${APP_CREATED_NOTE}\n\nThere is no free-text search in the Google Photos API: you cannot search for |
start_pick_session | write | 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.\n\nReturns a |
update_album | write | Change an album |
upload_file | write | Upload a photo or video from a path on the machine running this server, optionally straight into an album.\n\nThere is no API to delete a media item once uploaded. Requires confirm: true. |
upload_from_url | write | Download files from public URLs and add them to the user |
Trust audit
BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | FAIL |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- declared (5 observation(s))
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (5)
Report whether the server can reach Google Photos, which account it acts as, and which scopes the grant actually carries.\n\nCall this first when anything returns a permission error. A missing scope a
remove_from_album
.mcpbignore
@thenavidm/slipway, zod, @eslint/js, @types/node, eslint, typescript, typescript-eslint, vitest
Node 22 or newer; 1.2 ran on 20. Scripts keep working for success, a refused upload and missing setup; one that read exit 1 as an unknown command or read-only mode, or 5 as a bad argument, should read
Gates applied: critical_finding, no_behavioural_pass, undeclared_transfer.
20f37801e3eefull audit observations/trust-audit/mcp-server/thenavidm__google-photos-mcp-cli.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-11 | 20f37801e3ee | BLOCK | D | 69 | first audit |
Questions
What is the google-photos-mcp-cli MCP server?
Google Photos MCP server and CLI for Claude Code, Codex and AI agents. 26 tools for the photo picker, uploads, albums, enrichments, descriptions and app-created media.
What tools does google-photos-mcp-cli expose?
26 in total: 16 read-only, 9 that write, and 1 that can delete or overwrite (remove_from_album). Every one is listed on this page with its risk.
Is google-photos-mcp-cli safe to connect to an agent?
No — not without reading the findings first. The audit graded it D (69/100) and found 1 critical or high issue in the source. Each one is listed on this page with the file and line it is on. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does google-photos-mcp-cli need?
It reads GOOGLE_PHOTOS_CLIENT_SECRET and GOOGLE_PHOTOS_REFRESH_TOKEN from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How current is this page?
The grade is for one exact copy of the source (20f37801e3ee), read on 2026-10-11. The repository is watched and re-audited when it changes.