Google Photos MCP Server & CLI

A free, open source Google Photos MCP server and CLI that lets Claude Code, Codex, Cursor and other AI agents pick photos, build albums and upload to Google Photos.

Navid Moazzezby Navid Moazzez·Updated Oct 5, 2026·13 min read·
Your computer
  1. 1

    Get your refresh token once in a terminal, with your client's ID and secret.

    A browser opens for you to approve, then the terminal prints a refresh token. That token goes in the next step. Put your own client ID, secret and refresh token in place of the examples.

    export GOOGLE_PHOTOS_CLIENT_ID=your-client-id
    export GOOGLE_PHOTOS_CLIENT_SECRET=your-client-secret
    npx -y @thenavidm/google-photos-mcp-cli@latest login
  2. 2

    Add it with a single command in a terminal.

    Put your own client ID, secret and refresh token in place of the examples.

    claude mcp add google-photos \
    -e GOOGLE_PHOTOS_CLIENT_ID=your-client-id \
    -e GOOGLE_PHOTOS_CLIENT_SECRET=your-client-secret \
    -e GOOGLE_PHOTOS_REFRESH_TOKEN=your-refresh-token \
    -- npx -y @thenavidm/google-photos-mcp-cli@latest
  3. 3

    In Claude Code, type /mcp. Google Photos should show as connected.

    /mcp

Needs Node 22 or newer and an OAuth client from your own Google Cloud project. Set it up in about 10 minutes.

It's free and open source. If it saves you time, star it on GitHub, so more people find it.

Rate this tool

This free Google Photos MCP server and CLI gives your AI real access to Google Photos. It opens Google's photo picker, builds albums with captions and maps, uploads, writes descriptions and handles several Google accounts.

It's one install with two ways in. Claude, Codex, Cursor or any other MCP app calls its 26 tools for you, and the same tools work as a CLI that agents like Claude Code, Codex and OpenCode run, or that you type yourself.

In this guide, I'll show you:

  • What the Google Photos MCP server & CLI is, and what you can ask it
  • How to install it and check that it works
  • When to use the MCP server, and when the CLI
  • Every tool, and how to keep your account safe

Every tool on this page comes from the server itself, and every cost was measured in Claude Code.

key_takeaways.mdTL;DR

Key takeaways

It gives your AI 26 tools for Google Photos: the photo picker, albums with captions and maps, uploads and descriptions.
It works with several Google accounts from one server.
Uploading waits for your approval, because Google's API can't delete an upload afterward.
The same tools run as a CLI, which costs your AI nothing until it runs.

What is the Google Photos MCP server & CLI?

The Google Photos MCP server & CLI is a free, open source program that lets AI agents work with your Google Photos for you, in two ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to Google's Photos APIs.

The CLI is the same program as commands. google-photos-cli list-albums runs the same code your AI runs when you ask which albums it made, whether an agent like Claude Code runs it or you do.

In an AI OS, the layer that connects your AI to your context, your data and your tools, a server like this is how your AI reaches Google Photos. I explain how the parts fit together in how to build an AI operating system, and here's how I use AI myself.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Let me pick some photos, then tell me what I chose.
Put these 6 product shots in a new album called Q3 Launch.
Write a description on everything in the launch album.
Rename the Iceland album and set the third photo as its cover.
Upload this to my brand account, not my personal one.
Add a caption between the second and third photo, then a map from Reykjavik to Vik.

The last one shows why this is useful. A caption or a map sits right between the photos in an album, which makes it read like a story, and almost nothing outside Google's own app can add one.

It works well next to my Apple Photos MCP server and Adobe Firefly MCP server, so your AI can search your Apple Photos library and expand a photo in Adobe Firefly in the same chat. Every server I've made is on my MCP servers page.

For the photos themselves, my free HEIC to JPG converter and image resizer help too.

How to install the Google Photos MCP server

Pick your app in the box at the top of this page. You get a refresh token once in a terminal, then add the server to your app with a single command or a pasted block.

Windsurf, Zed and Cline take the same server, though they don't have a tab in the box yet. Follow the box's Cursor tab, and put its block here instead:

AppWhere the block goes
WindsurfIn the Cascade panel, open the Actions menu (…) and choose Open MCP config file, then paste the block.
ClineClick the MCP Servers icon in the Cline panel, open the Configure tab, click Configure MCP Servers, and paste the block.
ZedGo to Settings, then AI, then MCP Servers, and choose Add Server, then Add Local Server. Enter the block's command, arguments and variables, and Zed saves them under context_servers.
Before you start0/4

Watch out: Google removed full-library reading for outside apps in 2025. This server sees photos you pick in Google's picker and photos it uploaded itself, never your whole library.

Set up Google Photos

Google Photos has no API keys, and service accounts don't work for it. The only way in is an OAuth client in a Google Cloud project you own. It's free, and Google won't ask for a card.

Make your Google Cloud client0/6
https://www.googleapis.com/auth/photospicker.mediaitems.readonly
https://www.googleapis.com/auth/photoslibrary.appendonly
https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata
https://www.googleapis.com/auth/photoslibrary.edit.appcreateddata

Older guides ask for photoslibrary or photoslibrary.readonly. Don't add those: Google removed them on April 1, 2025, and asking for one fails the sign-in.

Watch out: While the consent screen is in Testing, your sign-in runs out after 7 days and the setup stops working. Set the publishing status to In production on the Audience page, which needs no review for your own use.

Get your refresh token

export GOOGLE_PHOTOS_CLIENT_ID="your-client-id"
export GOOGLE_PHOTOS_CLIENT_SECRET="your-client-secret"
npx -y @thenavidm/google-photos-mcp-cli login

A browser opens. Sign in as the account with the photos, click past the unverified-app warning, and approve, and the terminal prints a refresh token. Treat that token like a password.

Check that it works

Run the doctor. It checks your client, your token and every scope, and names the one that's missing.

npx -y @thenavidm/google-photos-mcp-cli doctor

When it passes, restart your app and ask it to open the photo picker.

In Claude Code, /mcp also shows whether the Google Photos server is connected. It's one of the Claude Code commands worth knowing.

Use the Google Photos CLI

The CLI is the same 26 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so list_albums runs as google-photos-cli list-albums.

npm install -g @thenavidm/google-photos-mcp-cli
google-photos-cli
google-photos-cli list-albums
google-photos-cli quota-status

The bare google-photos-cli lists every command, google-photos-cli which <words> finds the command for a task, and google-photos-cli <command> --help shows what a command takes. Uploading needs --confirm, the terminal's version of your approval.

google-photos-cli install <app> adds the server to Claude Code, Codex, Claude Desktop, Cursor, VS Code or Gemini CLI, in each app's own format.

These are the flags you'll use most:

FlagWhat it does
--jsonPrints JSON
--compactPrints the JSON on one line
--select a,b.cKeeps only those fields, and a dotted path goes deeper
--agentMachine mode: compact JSON, no prompts, and it never confirms anything
--confirmLets a write that asks first go ahead
--dry-runShows what a write would do, without doing it

A script can branch on the exit code:

Exit codeWhat it means
0It worked
1Something unexpected went wrong
2The command was typed wrong, or a write needed --confirm
3It wasn't found
4Google Photos rejected the credentials
5Google Photos failed or couldn't be reached
7You hit a rate limit, so wait and try again
10Nothing is set up yet

MCP server or CLI: which one?

Both are the same program with the same 26 tools. The difference is when your AI pays for them, in the tokens it reads.

Every message, in an app that loads every tool
MCP server
10,200 tokens
CLI
Nothing
Every message, in Claude Code
MCP server
900 tokens
CLI
Nothing
When Google Photos comes up
MCP server
Nothing more, or in Claude Code the tools it picks
CLI
3,900 tokens, once
20 messages with Google Photos in one, every tool loaded
MCP server
203,000 tokens
CLI
3,900 tokens
Works in Claude Desktop's chat
MCP server
Yes
CLI
No, there's no terminal there
Works in a script, a cron job or CI
MCP server
No
CLI
Yes

An app that loads every tool up front sends the full list with every message, whether you mention Google Photos or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.

The CLI costs nothing until Google Photos comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 160 tokens.

When the whole conversation is about Google Photos, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.

How to spend less

In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.

Turn the server off when you aren't using it. In Claude Code that's the /mcp panel, and every AI app has its own switch. GOOGLE_PHOTOS_READ_ONLY=1 cuts it to the 15 reading tools.

Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.

Every number here was measured on October 5, 2026 in Claude Code 2.1.286 with Claude Opus 5.5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.

What Google Photos lets an outside app do

Google removed full-library reading for outside apps on March 31, 2025. So an empty list means the server hasn't uploaded anything yet, not that you have no photos, and the picker is how your AI sees the rest.

There's no delete and no sharing through the API, for any app. An upload stays until you remove it by hand in Google Photos, and you share an album from the app yourself.

There's no free-text search either, so "beach" finds nothing. Google's own content categories are the closest thing, and describe_filter_capabilities lists them.

A photo's base_url expires in about an hour, so download_media_item and download_picked fetch a fresh one for you.

Every Google Photos tool

The tables below list all 26 tools, grouped the way the repo groups them. Of these, 15 only read, and 11 change something in your Google Photos.

The photo picker

start_pick_session
What it does
Open a Google Photos picker so the user can choose photos and videos from their ENTIRE library.
Kind
Reads
check_pick_session
What it does
Poll a picker session started by start_pick_session.
Kind
Reads
list_picked_media
What it does
Return the media items the user selected in a picker session.
Kind
Reads
download_picked
What it does
Fetch the bytes of an item the user picked, returned as base64 with its mime type.
Kind
Reads

Albums

create_album
What it does
Create a new, empty album in the user's Google Photos.
Kind
Writes
list_albums
What it does
List the albums this app created, newest first.
Kind
Reads
get_album
What it does
Fetch a single album by id, including its item count and cover photo.
Kind
Reads
update_album
What it does
Change an album's title, its cover photo, or both.
Kind
Writes
add_to_album
What it does
Add media items this app created to an album this app created.
Kind
Writes
remove_from_album
What it does
Take media items out of an album.
Kind
Writes
add_album_enrichment
What it does
Insert an enrichment into an album: a text caption, a named location, or a map between two places.
Kind
Writes

Photos it made

list_app_media
What it does
List media items, newest first, optionally scoped to one album.
Kind
Reads
search_library
What it does
Filter media by date range, content category, media type or favourites.
Kind
Reads
describe_filter_capabilities
What it does
Return the exact content categories, media types and feature filters search_library accepts, plus what the Google Photos API cannot do.
Kind
Reads
get_media_item
What it does
Fetch a single media item by id, with its dimensions, creation time and description.
Kind
Reads
get_media_items
What it does
Fetch up to 50 media items by id in one call.
Kind
Reads
update_media_description
What it does
Write the description shown under a photo or video in Google Photos.
Kind
Writes
download_media_item
What it does
Fetch the bytes of a media item this app uploaded, returned as base64 with its mime type.
Kind
Reads

Uploads

upload_from_url
What it does
Download files from public URLs and add them to the user's Google Photos, optionally straight into an album.
Kind
Asks first
upload_file
What it does
Upload a photo or video from a path on the machine running this server, optionally straight into an album.
Kind
Asks first
save_to_library
What it does
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.
Kind
Asks first
create_album_with_media
What it does
Create an album and upload files into it in a single step.
Kind
Asks first

Accounts and limits

list_accounts
What it does
Show every Google account this server can act as, and which one acts when a tool names none.
Kind
Reads
auth_status
What it does
Report whether the server can reach Google Photos, which account it acts as, and which scopes the grant actually carries.
Kind
Reads
quota_status
What it does
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.
Kind
Reads
raw
What it does
Escape hatch for an endpoint this server does not wrap.
Kind
Writes

Is the Google Photos MCP server safe?

Writes work from the start. Uploading is the one thing that asks first, because nothing in Google's API can delete an upload afterward, so four tools ask first. They're the ones marked "Asks first" in the tool tables above.

Making, renaming and filling albums don't ask, because each is easy to change back in Google Photos.

When your AI calls one of them, the call needs a yes first. Where you use it decides who gives it:

  • Claude Code (2.1.246 and later) asks you before every call, in every one of its permission modes.
  • An app that can show forms asks you in a form.
  • Any other app takes your AI's confirm: true as the yes, so tell your AI to check with you first.
  • An agent with no person to ask needs GOOGLE_PHOTOS_CONFIRM=model, so its confirm: true counts in every app.
  • In a terminal, you add --confirm to the command.

If the answer is no, nothing reaches Google Photos.

Make it read-only

Set GOOGLE_PHOTOS_READ_ONLY=1 and every write disappears from the tool list, leaving 15 reading tools. GOOGLE_PHOTOS_ALLOW_DESTRUCTIVE=0 is the middle setting: ordinary edits still work, and uploading doesn't.

Keep a log of every write

Set GOOGLE_PHOTOS_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked, with what it was about to do and who approved it.

Watch out: Album titles, descriptions and file names can carry any text, and one can try to give your AI orders. Treat everything read back as data, and use GOOGLE_PHOTOS_READ_ONLY=1 for an agent working on its own.

Your data

Nothing goes anywhere but Google's Photos APIs. Your client ID, secret and refresh token stay in your app's config or your shell, and there's no tracking of any kind.

To disconnect, remove the app at myaccount.google.com/permissions. That cuts off every token from that client at once.

Connect more than one Google account

Run the login step once per account, then list them in GOOGLE_PHOTOS_ACCOUNTS as JSON. Every tool that acts as you takes an optional account, so you can say which one gets the upload.

Google Photos MCP server settings

Every setting is an environment variable, in your app's config or your shell.

GOOGLE_PHOTOS_CLIENT_ID
Default
none
What it does
Holds your OAuth client's ID
GOOGLE_PHOTOS_CLIENT_SECRET
Default
none
What it does
Holds your OAuth client's secret
GOOGLE_PHOTOS_REFRESH_TOKEN
Default
none
What it does
Holds what the login step printed
GOOGLE_PHOTOS_ACCOUNTS
Default
none
What it does
Lists several Google accounts, as JSON
GOOGLE_PHOTOS_DEFAULT_ACCOUNT
Default
the first one
What it does
Picks the account that acts when a tool names none
GOOGLE_PHOTOS_READ_ONLY
Default
0
What it does
1 hides every write
GOOGLE_PHOTOS_ALLOW_DESTRUCTIVE
Default
1
What it does
0 blocks uploading
GOOGLE_PHOTOS_AUDIT_LOG
Default
none
What it does
Logs every attempted write to a file
GOOGLE_PHOTOS_AUTH_PORT
Default
4180
What it does
Sets the port the login step listens on
GOOGLE_PHOTOS_REQUEST_TIMEOUT_MS
Default
30000
What it does
Per-request deadline
GOOGLE_PHOTOS_MAX_RETRIES
Default
2
What it does
Retries on 429 and 5xx
GOOGLE_PHOTOS_SURFACE
Default
full
What it does
search lists three tools that find, describe and run the rest
GOOGLE_PHOTOS_TOOL_TIMEOUT_MS
Default
none
What it does
Gives up on any tool after this many milliseconds
GOOGLE_PHOTOS_CONFIRM
Default
human
What it does
model lets your AI's confirm: true approve on its own, for an agent with no person to ask
GOOGLE_PHOTOS_HTTP_PORT
Default
8787
What it does
Sets the port for --http
GOOGLE_PHOTOS_HTTP_HOST
Default
127.0.0.1
What it does
Sets the address for --http, and any other needs a token
GOOGLE_PHOTOS_HTTP_TOKEN
Default
none
What it does
Sets the bearer token every --http request needs
GOOGLE_PHOTOS_HTTP_ALLOWED_ORIGINS
Default
none
What it does
Lists other websites allowed to call --http, comma separated
GOOGLE_PHOTOS_DEBUG
Default
off
What it does
1 prints debug lines

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

What you seeWhat to do
Everything returns a permission errorThe token is missing a scope. Adding one in the console doesn't update an old token, so run the login step again
invalid_grant, after working last week7 days passed with the consent screen in Testing. Set it to In production, or run the login step again
redirect_uri_mismatch during loginThe redirect URI isn't exactly http://localhost:4180, with http and no trailing slash
access_denied after signing inYour account isn't a test user, or you signed in as another account
A read returns nothingThat's almost always right, because the server hasn't uploaded anything yet. Use the picker
RESOURCE_EXHAUSTEDYou hit Google's daily limit. quota_status shows it, and it resets at midnight UTC

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

More free tools for your photos

Turn photos into a carousel for Instagram, or into images to share.

FAQs about the Google Photos MCP server & CLI

Here are the questions people ask most about the Google Photos MCP server and CLI.

The Google Photos MCP server & CLI is a free, open source program that lets an AI app like Claude, Codex or Cursor work with your Google Photos.

It has 26 tools for the photo picker, albums, uploads, descriptions, album captions and maps, and several Google accounts, and the same tools run as a CLI that agents like Claude Code and Codex use, or that you type yourself.

An MCP server is a standard way to give an AI app real access to a tool, so it can act instead of guessing.

MCP stands for Model Context Protocol, and Claude, Codex, Cursor and many other AI apps speak it.

Every server I've made is on my MCP servers page.

The Google Photos CLI is the same program as the Google Photos MCP server, run as commands.

AI agents like Claude Code, Codex and OpenCode run them for you, and you can type them in a terminal or a script.

One npm package installs both.

Use the Google Photos MCP server in an AI app with no terminal, like Claude Desktop's chat, and the CLI in a terminal, a script or a cron job.

In an AI app that can run commands, like Claude Code, Codex or Cursor, the CLI is the lighter choice, because it costs nothing until it runs.

Yes, the Google Photos MCP server is free and open source under the MIT license.

Google's Photos APIs and the Cloud project are free too, so the only thing you pay for is your own AI app.

No, the Google Photos MCP server sees photos you pick in Google's picker and photos it uploaded, because Google removed full-library reading for outside apps in 2025.

No outside app can read your whole library anymore.

Your Google Photos setup stops after 7 days when the consent screen is still in Testing.

Set its publishing status to In production, which needs no review for your own use.

No, the Google Photos MCP server can't delete anything, because Google's API has no delete for any app.

That's why uploading asks first.

Yes, the Google Photos MCP server connects as many Google accounts as you set up.

Every tool takes an optional account, so you can say which one acts.

The Google Photos MCP server works with any app that speaks MCP.

That includes Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf, Zed, Cline, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Antigravity and Hermes.

I did.

I'm Navid Moazzez, and I made the Google Photos MCP server & CLI as one of my free tools on navid.me.

You can read more about me.

The code is on GitHub under the MIT license, and the package is on npm.

More MCP servers & CLIs

Related free tools

Navid Moazzez

AI business strategist & AI OS builder

Navid Moazzez helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life.

Navid.me is reader-supported. When you buy through links on this site, I may earn an affiliate commission. Read the affiliate disclaimer.

Free AI newsletter

The most actionable AI newsletter for founders

Every week, get proven AI strategies, curated tools, and step-by-step systems to grow your audience, create better content, and build a profitable creator business.

No fluff, no filler, no BS. Just five minutes each week that might level up your online business and life.

P.S. Sign up now to get free access to my ultimate AI tools guide for creators.

Loved by 10,000+ readers
Loved by 10,000+ readers