Google Photos MCP Server & CLI

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 2 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.

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.

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.

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.

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.

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 auth

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.

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, and google-photos-cli <command> --help shows what a command takes. Uploading needs --confirm, the terminal's version of the check your AI has to pass.

These flags work on every command:

A script can branch on the exit code:

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.

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 September 27, 2026 in Claude Code 2.1.257 with Claude Opus 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

All 26 tools, grouped the way the repo groups them. 15 only read, and 11 change something in your Google Photos.

The photo picker

Albums

Photos it made

Uploads

Accounts and limits

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 4 tools refuse to run until your AI passes confirm: true. 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.

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.

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 auth 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.

Troubleshooting

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

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.