search_photosLABSCO SUMMARY
The Picker path is why this still reaches the whole library.
Google narrowed the Library API scopes, and the answer here is a two-step handshake: create a picker session, open the URL, choose photos, poll for the result. It is more clicking than an API call, and it is the reason browsing the full library still works. Two practical notes: the first OAuth run has to happen over HTTP before Claude Desktop's stdio mode will work, and Google's daily quota is 10,000 requests.
What it is
A Google Photos server that combines the Library API for search and writes with the Picker API for full-library browsing. Tokens are stored in the OS keychain and refreshed automatically.
What you get
- 19 tools in total, split across search, writes, picking and auth
- search_photos, search_photos_by_location and search_media_by_filter cover text, place, date range, category, media type, favourites and archived state; describe_filter_capabilities returns the full filter reference
- get_photo returns one photo's details, optionally base64-encoded; list_albums, get_album, list_album_photos and list_media_items walk the library
- create_album, upload_media, add_media_to_album and create_album_with_media handle writes, with a maximum of 50 items per batch call
- add_album_enrichment adds text or location to an album and set_album_cover picks its cover photo
- create_picker_session returns a URL you open in a browser; after you choose photos, poll_picker_session returns the selection
- auth_status and start_auth tell you whether the OAuth flow has completed and restart it if not
Requirements
Node.js 22.22 or newer, a Google Cloud project with the Photos Library API enabled, and OAuth 2.0 web-application credentials with http://localhost:3000/auth/callback as an authorised redirect URI. GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and GOOGLE_REDIRECT_URI go in the environment. Authentication must be completed in HTTP mode first — start the server, visit http://localhost:3000/auth — after which stdio mode works.
Setup effort
Build from source — git clone https://github.com/savethepolarbears/google-photos-mcp.git
USE CASES
01
Finding photos you can describe but not name
Search by text, place, date range or category, and filter by media type or favourites.
02
Handing the assistant photos you choose yourself
A picker session opens in the browser; polling returns exactly what you selected.
03
Getting a shoot into a new album
Create the album and upload the files in a single call, up to 50 at a time.
04
Tidying up albums
Add text or location enrichments and set the cover photo.
05
Working out why calls fail
Check whether the OAuth flow ever finished before blaming the query.
19 tools
Listed in project docs. Your client may show a different list.
search_photos_by_locationsearch_media_by_filterget_photolist_albumsget_albumlist_album_photoslist_media_itemsdescribe_filter_capabilitiescreate_albumupload_mediaadd_media_to_albumcreate_album_with_mediaadd_album_enrichmentset_album_covercreate_picker_sessionpoll_picker_sessionauth_statusstart_authBEFORE YOU INSTALL
What to know first
Tools you get
19 tools named in the project's documentation. Since Google's March 31, 2025 scope change, text search reaches only app-created content; browsing your full library uses create_picker_session and poll_picker_session. Bulk operations cap at 50 files, and HTTP transport does not work from browsers.
Requires
- Node.js 22.22+
- GOOGLE_CLIENT_ID in your environment
- GOOGLE_CLIENT_SECRET in your environment
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
You clone and build this one yourself.
Server setup
Create a Google Cloud project, enable the Photos Library API, create OAuth 2.0 (Web application) credentials and add http://localhost:3000/auth/callback as an authorized redirect URI
TERMINAL
git clone https://github.com/savethepolarbears/google-photos-mcp.git
cd google-photos-mcp
npm installCopy .env.example to .env and set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and GOOGLE_REDIRECT_URI
TERMINAL
npm run buildStart in HTTP mode with npm start, then visit http://localhost:3000/auth to complete the Google OAuth flow
Once authenticated, run it in STDIO mode for Claude Desktop:
TERMINAL
npm run stdioMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"google-photos": {
"command": "node",
"args": [
"<YOUR_PATH_TO_GOOGLE_PHOTOS_MCP>/dist/index.js",
"--stdio"
],
"env": {
"GOOGLE_CLIENT_ID": "<YOUR_GOOGLE_CLIENT_ID>",
"GOOGLE_CLIENT_SECRET": "<YOUR_GOOGLE_CLIENT_SECRET>",
"GOOGLE_REDIRECT_URI": "http://localhost:3000/auth/callback"
}
}
}
}
