photos-mcp

MCP server for Google Photos libraries. An assistant can find photos with Google Photos' own search (people, places, things, text in images, dates), look at them, show them to the person as a gallery, add photos and videos (from the person's phone or computer through a one-time upload page, from a link, or a file the assistant has; Uploading), delete them (to the trash, where Google keeps them 60 days, and back again) and organise albums (create one, add photos, take them out, delete it). The tools that take something away are marked destructive, so MCP clients ask the person before each call; nothing empties the trash, archives, edits or shares a photo (Safety). It serves one library, or one per person behind an authenticating proxy (Accounts), where each person connects their own Google account through an authenticated owner page (Signing in with a link).

Google's official Library API only sees media created by the calling app since 2025-03-31, so photos-mcp speaks the private batchexecute RPCs that photos.google.com itself uses, with the cookies of a signed-in browser.

Unofficial. photos-mcp is not affiliated with or endorsed by Google. It relies on an undocumented web API that can change at any time, and automated access may conflict with Google's terms of service: use it only with your own account, at your own risk. The session snapshot it reads carries full authority over that Google account; keep it private (the tools create it 0600 in a 0700 directory).

The repository and the PyPI package are google-photos-mcp; its commands are google-photos-mcp (also installed as photos-mcp) and photos-mcp-session. It is developed and tested on Linux (Python 3.12+).

your browser profile ──photos-mcp-session──▶ session dir {cookies.txt, meta.json}
                                                      │ read-only
MCP client (stdio, or HTTP + bearer) ◀──▶ photos-mcp ─┘   state dir: budgets, breaker, thumbnail cache
                                              │ hosted owner connections
                                    photos-mcp-login: one browser profile per account ──▶ their snapshots

Quick start

1. Install (the session extra adds the browser exporter):

   uv tool install "google-photos-mcp[session]"
   photos-mcp-session browser install   # once: Playwright's Chromium (--with-deps also installs
                                        # its Linux system libraries, which needs root)

   or use the image ghcr.io/benjamin-di/google-photos-mcp for the server.

2. Create a session snapshot in a private directory, one of two ways:

   • Cookies from your own browser (schema 1). In Chrome or Chromium, open photos.google.com and one photo, export the cookies as a Netscape cookies.txt (any cookie-export extension), then:

     photos-mcp-session import --cookies cookies.txt --email you@example.com \
         --user-agent "<navigator.userAgent of that browser>" --out ~/.photos-mcp/session

     Delete the exported cookies.txt afterwards. Signing out of that browser ends the session, and the snapshot is never refreshed: import again when photos-mcp reports session_expired (its photos_canary calls an imported snapshot snapshot_stale after 3 h; that is expected).

   • Dedicated browser profile (experimental: schema 2, the browser's real request headers, refreshable unattended). Sign in by hand once, then export:

     photos-mcp-session browser login  --profile ~/.photos-mcp/profile
     photos-mcp-session browser export --profile ~/.photos-mcp/profile --out ~/.photos-mcp/session \
         --expected-email you@example.com

     Both commands open a browser window, so they need a display (on a server: xvfb-run -a photos-mcp-session ...). If Google refuses the sign-in in Playwright's Chromium, use an installed Google Chrome with --channel chrome, for login and export alike. One command at a time per profile (the browser locks it). export never signs in; when the profile is signed out, run login again.

3. Run the server. For a local client (Claude Desktop, Claude Code, ...) over stdio, with the absolute path of photos-mcp (command -v photos-mcp; desktop apps may not share your shell's PATH):

   {
     "mcpServers": {
       "photos": {
         "command": "/home/you/.local/bin/photos-mcp",
         "args": ["--transport", "stdio"],
         "env": {
           "GOOGLE_PHOTOS_EXPECTED_EMAIL": "you@example.com",
           "PHOTOS_SESSION_DIR": "/home/you/.photos-mcp/session",
           "PHOTOS_STATE_DIR": "/home/you/.photos-mcp/state"
         }
       }
     }
   }

   Or over HTTP (/mcp, bearer required; /health is open). The image listens on port 8000; publish it on localhost and run it as your own uid so it can read the snapshot. Before starting HTTP, prepare the private state root and its four deployment records using first-time HTTP setup, with scope reader. An empty directory alone is insufficient. Keep existing records when upgrading; do not rerun first-time setup on retained state.

   TOKEN="$(openssl rand -hex 32)"; echo "bearer token: $TOKEN"
   docker run -d --name photos-mcp -p 127.0.0.1:8000:8000 --read-only --user "$(id -u):$(id -g)" \
     -e MCP_BEARER_TOKEN="$TOKEN" -e GOOGLE_PHOTOS_EXPECTED_EMAIL=you@example.com \
     -v ~/.photos-mcp/session:/session:ro -v ~/.photos-mcp/state:/state \
     ghcr.io/benjamin-di/google-photos-mcp

   Clients send Authorization: Bearer <token> to http://127.0.0.1:8000/mcp. Put a TLS reverse proxy in front before exposing it beyond localhost. Without Docker, photos-mcp serves HTTP on 127.0.0.1:8000 (--host, --port) and needs the same provisioned reader root at PHOTOS_STATE_DIR. Stdio does not require these HTTP deployment records.

4. Keep the session fresh. Google rotates session cookies. With a browser profile, re-run browser export regularly, for example hourly from cron:

   0 * * * * flock -n ~/.photos-mcp/export.lock xvfb-run -a photos-mcp-session browser export --profile ~/.photos-mcp/profile --out ~/.photos-mcp/session --expected-email you@example.com

   photos-mcp picks up each new generation by itself. photos_status shows the snapshot's age.

Related MCP server: Google Photos MCP

Privacy

• The images and metadata the tools return go to your MCP client and, through it, to the model provider it uses.

• photos_download (when PHOTOS_PUBLIC_URL is configured) makes JPEG copies for transfer to another tool. Each URL is a credential for one download within 10 minutes. Give it directly to the importing tool; opening it first consumes it. Copies default to 2048 px (up to 4096), contain no original EXIF metadata, and are not originals. Videos are refused. Outstanding copies are held in bounded memory (64 MiB); restarting revokes all links. A reverse proxy must forward only GET/HEAD of /downloads/<43-character base64url token>, without a query or Authorization header. WhatsApp clients with URL import can call send_file(recipient=..., source_url=<returned url>); a plain Google Photos item URL opens a sign-in page and cannot substitute for a file download.

• With sign-in links, the login service keeps each person's browser profile, which stays signed in to their whole Google account (not only Photos), and their snapshot. Whoever runs the server can use both: tell people so before they connect. They can end it any time in their Google Account (Security, Your devices).

• The state directory keeps a cache of thumbnails of your photos (up to PHOTOS_CACHE_MAX_BYTES, 2 GiB by default; 0 disables it). Treat it like the photos.

• The session directory and the browser profile give full access to the Google account.

• The server talks to nothing but Google's own photo hosts (see "Safety and Google posture"), except to fetch a file from a public link a caller gives photos_upload, and its logs carry no photo ids, URLs or cookies.

• A file being uploaded is held in an anonymous file under the state directory's uploads/ only until it is sent (nothing is left there, even after a crash).

Permissions

Human browser sign-in authenticates the owner who may manage a Google connection. MCP admission separately authenticates a client or workload and limits its audience, scopes and permitted tools. Photos then binds calls to the configured account and applies its own provider-operation allowlists, budgets and write rules. A successful Google sign-in grants no agent permission. Pocket ID is an example standard OIDC provider; another compatible provider can be configured. The private backend bearer and account header belong only to trusted application infrastructure.

See permission boundaries, revocation and remaining project checks for browser-session expiry, native default/further-account custody and recovery.

Tools

All are read-only (readOnlyHint) except photos_album_create, photos_album_add, photos_album_remove, photos_album_delete, photos_delete, photos_restore, photos_upload and photos_upload_link. Album removal/deletion and moving items to trash are destructive. photos_connect is a read-only local entry URL: it creates no sign-in attempt and changes no access. Upload links allocate bounded file-transfer capabilities; they are separate from browser identity and agent authorization. Gateway tool ceilings and client confirmation remain independent of these annotations. Arguments that fail the schema come back as the typed invalid_argument error naming the argument, never pydantic's raw text.

Items have one shape in search, list, album and get, every key present (null when unknown): {id, url, type, taken_at, tz_known, filename, description, place, favourite, archived}. url opens the item on photos.google.com (inside its album when listed from one); the person's own browser signs in, so it is also how they get an original. taken_at carries the item's UTC offset when tz_known; without a known offset it is the instant in UTC with Z (never a fake +00:00). Search records carry no place, so place is null there unless details=true, which reads each item's details (one item-info RPC per item, ten to a request; limit up to 20) and adds lat, lon and camera, filling place where the listing had none. photos_get adds source (how the item reached the library: mobile, web, shared, partnerShared, drive, pc, gmail, and android or ios) and original_quality. archived comes from the source for photos_list library (false) and archive (true), because live library records end before the flag; search and photos_get read it from the record; it is null where the record does not say (album items). Filenames come from a second RPC (EWgK9e); if it fails for any reason other than the session, the items go out with filename: null. Inline images are at most 1568 px; photos_download exports JPEG copies up to 4096 px for file transfer. Original files are not available. Listings carry coverage (pagination_complete, shared_partner: "not_covered", archive_included — false only for source=library — and cursor_recovered / dedupe_required / loop_detected when they apply) and freshness (generation, session_verified_at, served_at).

photos_list sources: library (newest first by taken date, archive excluded), archive, album, favourites and recently_added (newest upload first; both are the web app's own filtered views of the search RPC and include archived items), and trash (most recently deleted first; what photos_restore can bring back). from_date / to_date (YYYY-MM-DD, library and archive) bound the items' own local dates: the listing starts Google's timeline at the end of the range and stops once it has passed the start. media=photos|videos keeps one kind. A filtered listing reads up to 5 Google pages per call to find matches, so a page can hold fewer than limit items while next_cursor goes on.

photos_on_this_day reads one library page per earlier year, starting at that day (up to 100 items; more says the day holds more than shown or than one page could tell: list it with from_date=to_date), stops at the first year with nothing that old, and looks up all filenames in one RPC. "Today" is in PHOTOS_BUDGET_TZ.

Uploading

A photo or video reaches the library the way photos.google.com's own uploader sends it (docs/PAYLOADS.md): photos-mcp first asks whether the library already holds a file with the same SHA-1 (swbisb) and then sends nothing, else it sends the bytes to Google's resumable upload endpoint in 16 MiB chunks and makes the item from the upload token (mdpdU). Only photo and video formats Google Photos keeps are taken, told by their first bytes (JPEG, PNG, GIF, WebP, HEIC, AVIF, BMP, TIFF and the raw formats built on it; MP4, MOV, 3GP, AVI, MKV, WebM, WMV, MPEG), anything else is refused before it is stored. Each file is at most PHOTOS_UPLOAD_MAX_BYTES (2 GiB) and costs one unit of the daily write budget (two into an album) and three of the RPC budget whatever its size (the hash check, the upload endpoint, making the item); the item keeps the file's own date (EXIF), else its last-modified time. When the album step fails after the item was made, the answer still has the item, and its album carries that error. At most 2 files are received or sent at once on a server, by links and photos_upload alike: another one waits for a slot (up to 5 minutes on a link, 1 minute for the tool) before its bytes are read.

• The person's own files: photos_upload_link. With PHOTOS_PUBLIC_URL set, the tool gives the caller a link, PHOTOS_PUBLIC_URL/uploads/<id>, to a page where they pick photos and videos on their phone or computer; each goes straight into their own library (and into the album the link names, checked when it is made) and the page says what became of it. The same address takes one file per PUT from a client that has it on disk (an image an assistant made in a code sandbox, say): curl -T <file> -H 'X-File-Name: <name>' <url>, which answers with the new item. A link works for 60 minutes and 100 files, adds only to the account that asked for it (not one removed and added again since), and needs no bearer: its 256-bit id is the credential, so the reverse proxy must pass /uploads/<id> (GET and PUT, no query) through without one, as for sign-in links. A body that sends nothing for a minute is dropped. Links live in memory: a restart ends them.

• A link: photos_upload(url=...). The server fetches the file itself, guarded so a link can never reach into the network the server runs in: https on port 443 only; every address the host resolves to must be public, and the request goes to that address only (curl's resolve pin, no proxy, not even one from the environment); redirects, at most 3, are checked the same way; no cookies or credentials are sent, and the whole fetch, headers included, must finish within 10 minutes.

• Bytes the assistant has: photos_upload(data=...), base64 (standard or URL-safe, a data: URL prefix allowed), up to 10 MiB.

Photo cards

photos_show gives claude.ai, ChatGPT and other MCP Apps clients a gallery to draw for the person: thumbnail, date, the agent's note and a link that opens each photo in Google Photos. The thumbnails (320 px, from the same paced and cached image path as photos_view) travel inline in the result's _meta["photos/view"] as JPEG data: URLs, which the model is not sent; the card (ui://photos/view.html, src/photos_mcp/view.html) loads nothing else and opens links through the client. Clients without MCP Apps get the same items as JSON.

photos_canary is the real-path check for monitoring: one real check (an upstream library page of 1 item plus that item's thumbnail, bypassing the thumbnail cache, through the normal RPC, parser and image path, budgets and breaker); calls in between return the cached verdict with cached: true, unless a newer snapshot was published since: a verdict belongs to the generation it checked. An ok result and lasting failures (session, block, consent, budget, schema, media_session_required) are cached 55 min; transient ones (upstream_error, busy, stale_token, item_unavailable, internal_error) are re-checked after 5 min. ok is false on any error code, and with code snapshot_stale when the snapshot is older than 3 h (snapshot_age_s > 10800) or its verified_at lies more than 5 min in the future (negative snapshot_age_s); it never raises and never logs ids.

photos_status.last_error records real failures, item-level ones included (for example media_session_required on one thumbnail), but not the agent's own invalid_argument or invalid_cursor.

Cursors are server-side, scope-bound (query, source or album) and live 1 h. An expired cursor, or one from before a restart, is recovered by re-reading from the start and skipping what was delivered (at most 5 upstream pages: 500 items for the library and the archive, which use fixed Google pages of 100); the result says dedupe_required.

Errors

Errors are tool errors whose text is {"error": {"code", "next_step", "retryable"}}:

Liveness

Only positive evidence marks a session dead: a redirect to accounts.google.com or to Google's signed-out product page (www.google.com/photos/about), or another account than GOOGLE_PHOTOS_EXPECTED_EMAIL. That generation is then never sent to Google again; photos-mcp waits for a newer one. Everything else (a consent screen, an error page, a 5xx, a bare 401, an app page without its signed-in data) is reported and retried later with the same generation.

Safety and Google posture

• Album changes, uploads and the trash only. Reads go through GoogleTransport.rpc, which refuses any RPC id outside lcxiM EzkLib EWgK9e Z5xsfc snAcKc VrseUb fDcn4b EzwWhf swbisb zy0IHe (swbisb: does the library hold a file with this hash; zy0IHe: the trash). Changes go through GoogleTransport.write, which refuses any outside OXvT9d E1Cajb laUYf ycV3Nd LjmOue nV6Qv mdpdU XwAOJf (create an album; add items to an album or a shared one; remove items from an album or a shared one; delete an album; make an item from an upload; move items to the trash or back) and never retries a request that may have reached Google (outcome_unknown, logged). Nothing deletes for good: no builder empties the trash or deletes from it, and XwAOJf is built only into the trash and back. An upload's bytes go through GoogleTransport.upload_bytes to Google's upload endpoint only (/_/upload/uploadmedia/interactive, and the session address it answers with, which must be the same endpoint); nothing is in the library until mdpdU, so a failure there changes nothing. No builder exists for emptying the trash, archiving, favouriting, editing dates, places or descriptions, sharing, the locked folder or downloads; tests/test_safety.py checks the source for other RPC ids and builders, other hosts and other HTTP libraries.

• Removing and deleting are the client's to confirm. photos_album_remove, photos_album_delete and photos_delete are annotated destructiveHint, and the instructions tell the model to ask the person first and show what goes; configure your MCP clients to ask before each call of these three (their approval setting per tool). Each acts in one call. photos_album_remove touches only the ids the album's own listing holds (Google's remove RPC names no album, so a key from another album would act there); photos_delete only the items of this library, by the dedup keys the trash RPC takes; photos_album_delete only the account's own albums (a shared one is left to the app, since deleting it changes it for everyone in it). Every change is read back (added / removed from the album's counts, in_trash / restored from the trash, deleted from the album no longer opening), counts against PHOTOS_DAILY_WRITE_BUDGET (each account's own, 500 a day; one per item, upload or album) and is appended to audit.jsonl in the account's state directory (ids and counts only).

• Hosts: HTTPS only, photos.google.com, photos.fife.usercontent.google.com, lh[0-9].googleusercontent.com. Redirects are followed by hand, at most 3, inside that list; sign-in, consent and /sorry redirects are classified, never followed. The one exception is photos_upload(url=...), which fetches from the public host a caller names through photos_mcp.fetch (Uploading), never with Google's cookies.

• Pacing: RPCs and the app page one at a time, ≥350 ms apart plus jitter; image fetches up to 4 at a time, starts ≥100 ms apart; uploads up to 2 files at a time in slots of their own (a long upload never holds the RPC slot); 10 s connect / 20 s read, ≤2 retries on 5xx and network errors only. Daily budgets PHOTOS_DAILY_RPC_BUDGET (3000) and PHOTOS_DAILY_THUMB_BUDGET (2000).

• Request shape: the browser behind the snapshot is the source of truth. Each request uses meta.json's header values for its kind (page, rpc, image; or the UA-synthesised template where that kind fell back, see below), plus the request's cookie, referer and accept-encoding, all in Chrome's per-kind wire order (session.CANONICAL_ORDER). curl_cffi impersonates the newest chromeN profile with N ≤ chromium_major (the nearest one when none is older) with default_headers=False, so it adds no headers of its own. tests/test_curl_sender.py captures what goes on the wire and fails when the sample's Chrome is more than 4 majors past curl_cffi's newest profile (then make lock a newer curl_cffi).

• Untrusted bytes: RPC bodies ≤8 MiB and images ≤15 MiB, streamed; magic bytes before Pillow; a decompression-bomb warning is an error; JPEGs are draft()-reduced before load().

• Hygiene: tool output never carries exception text; logs carry RPC ids, host, status, bytes and ms only. Cookies stay in memory: allowlisted Set-Cookie updates are merged there and never written back. photos-mcp never rotates cookies. Tool errors are logged as one line, never with a traceback: INFO for the agent's own mistakes (invalid_argument, invalid_cursor), WARNING otherwise (the ToolError's log_level, which FastMCP and the tool-call log follow). An unexpected crash logs tool crashed: <type> at ERROR and answers internal_error.

Session snapshot

PHOTOS_SESSION_DIR (default /session, mounted read-only) holds:

• cookies.txt, Netscape format. Host-only rows have include-subdomains FALSE and no leading dot (the CDN's own OSID on photos.fife.usercontent.google.com); domain rows have TRUE and a leading dot. Rows for domains other than google.com, photos.google.com and photos.fife.usercontent.google.com are ignored.

• meta.json (schema 2): {"schema": 2, "generation": <int, monotonic>, "email", "account_index": 0, "user_agent", "chromium_major", "verified_at": <ISO 8601>, "headers": {"page": [[name, value], …], "rpc": […], "image": […]}}. It is written last, so it is the commit point. Each headers.<kind> is the ordered header list Chrome sent for one real request of that kind while the library loaded: names lower-case, at most 32 pairs, single-line values ≤ 512 chars, user-agent equal to user_agent, and only user-agent, accept, accept-language, content-type (rpc only), origin, x-same-domain, upgrade-insecure-requests, priority, sec-ch-ua* and sec-fetch-*. Other names are ignored, structural errors make the snapshot session_unavailable, and chromium_major must match the User-Agent. A kind without sec-fetch-site, sec-fetch-mode and sec-fetch-dest, or whose dest contradicts the kind (page document, rpc empty, image image), uses the synthesised template below for that kind only, logged once per generation without values; photos-mcp-session applies the same rule when it writes a snapshot. Values come from the browser, order from photos-mcp: a CDP capture reports names sorted, so every template is put in Chrome's per-kind wire order (session.CANONICAL_ORDER, recorded from a real Chrome with --log-net-log; tests/fixtures/chrome_wire_order.json keeps those names). The order covers the headers the transport adds too: referer, accept-encoding and cookie go last, before priority, as Chrome sends them; an unknown name goes just before sec-fetch-site.

• Schema 1 (no headers; what photos-mcp-session import writes) is read too: the templates are then synthesised from the User-Agent (its Chrome major in sec-ch-ua, its platform, Chrome's per-kind sec-fetch-* values), so they never contradict it.

meta.json is stat-ed on every call; a newer generation rebuilds the HTTP session and re-reads the page globals. A generation Google rejected is not retried. A checked-in sample lives in tests/fixtures/session/ (meta.json schema 2, meta.schema1.json schema 1). Anything that writes this format can keep the session for photos-mcp; nothing flows back from photos-mcp to it.

Configuration

photos-mcp [--transport http|stdio] [--host 127.0.0.1] [--port 8000] (the image passes --host 0.0.0.0): HTTP serves stateless streamable HTTP with JSON replies on /mcp and liveness on /health (it never calls Google).

Accounts

Hosted account management uses POSIX process locks to serialize account adoption and control changes. Single-account local stdio remains independent of hosted OIDC.

One server can keep several people's libraries apart behind an authenticating reverse proxy that knows who is calling. Each account has its own snapshot, state (budgets, last error, the generation Google rejected), thumbnail cache, cursors and canary; Google's pacing and the breaker after pushback are shared, because Google sees one client.

• The default account is the setup above: the snapshot in PHOTOS_SESSION_DIR, GOOGLE_PHOTOS_EXPECTED_EMAIL, its state right in PHOTOS_STATE_DIR. A one-account server keeps that layout. With hosted connections, its owner connects and reconnects through the same authenticated page as other accounts. Its native profile stays with its existing custodian (setup and recovery).

• Further accounts live in PHOTOS_STATE_DIR/accounts/<id>/ (ids are 1-32 lower-case letters, digits or dashes), with their snapshots in PHOTOS_ACCOUNT_SESSIONS_DIR/<id>/, which the login service writes after the person signed in through a link.

• Budgets are split, not added. PHOTOS_DAILY_RPC_BUDGET and PHOTOS_DAILY_THUMB_BUDGET stay the server's daily totals. Each further account has its own share; the default account gets what is left. A change applies on the next call. If the totals are lowered below the shares, every share shrinks in proportion (the default account then gets nothing).

• Which account a request is for comes from PHOTOS_TRUSTED_ACCOUNT_HEADER, read only on requests that carry the first token in MCP_BEARER_TOKEN: that one is the proxy's, so only the proxy may hold it, and the proxy must remove any copy of the header a client sends. With that token the header is required (a request the proxy did not name is refused, never served as the default account). Any other token acts for the default account, and a header with it is refused. A header naming an account that is not set up, or naming it twice, gets account_not_connected. Over stdio there is no header: always the default account.

• An account serves one Google address. It is bound by the first sign-in through its link (or given with --email when the account is added) and never changes: a sign-in as another Google account, or as one another account here serves, is refused. Until it is bound, the account serves nothing (not_signed_in). Only that address's library is ever served, even if the profile also holds another Google sign-in.

• Removing and re-adding an id gives a new account: nothing of the old one (state, cache, browser profile, snapshot) carries over; admin account add asks the login service to clear any leftover profile first.

docker exec photos-mcp photos-mcp admin account add second --rpc-budget 1500 --thumb-budget 1000
docker exec photos-mcp photos-mcp admin account budget second --rpc-budget 1000 --thumb-budget 800
docker exec photos-mcp photos-mcp admin account list      # addresses, shares, session and keeper state
docker exec photos-mcp photos-mcp admin account remove second   # also asks the login service to delete
                                                                # its browser profile and snapshot

Signing in with a link

With the login service and a public address, a person connects their own Google account through My connections, at <PHOTOS_CONNECTIONS_PUBLIC_URL>/connections/. They sign in to their identity provider in their own browser, then connect, reconnect or disconnect their own Google Photos account. Pocket ID works as a standard OIDC provider; another provider with the same signed claims can use the same interface.

photos_connect returns the permanent My connections URL with expires_at: null. Requesting it never starts, replaces or pauses a connection; only the signed-in owner can start a sign-in. Browser sign-in is mandatory whenever sign-in links are configured: missing OIDC configuration refuses startup, and a forwarded link cannot select another person's account. Existing snapshots and their formats stay valid. See Connections setup and recovery.

• The login service (photos-mcp-login, image ghcr.io/benjamin-di/google-photos-mcp-login, built from Dockerfile.login) keeps each further account's browser profile in PHOTOS_LOGIN_PROFILES and writes the snapshots to PHOTOS_LOGIN_SESSIONS (the server's PHOTOS_ACCOUNT_SESSIONS_DIR, mounted read-only there). Run it beside the server on a private network with the same PHOTOS_LOGIN_TOKEN; it needs outbound access to Google. One browser runs at a time. The default account uses its existing maintenance custodian, profile and lease, exposed privately through PHOTOS_DEFAULT_LOGIN_URL; Connections setup describes its fixed service contract.

• The window. The page shows Google's sign-in page, running in that account's profile on a virtual display, through noVNC relayed by the server. Nothing on the sign-in is automated: the person does every step, Google's own checks included. Passkeys do not work in a remote window: if Google offers one, choose another way, and sign in with the password and the code or prompt Google asks for.

• The window is locked down, because the login service keeps every further account's profile and snapshot: Chromium runs in kiosk mode (no address bar, tabs or menus) under signin-window's managed policy (installed by the image) that refuses file://, chrome://, view-source:, data: and DevTools pages, file dialogs, downloads, printing and offers to save the password, and top-level pages are limited to Google's sign-in hosts. The service opens no window without the policy (PHOTOS_LOGIN_UNMANAGED_BROWSER=1 overrides that, for trying it out on a computer of your own only). The live view works only while the profile is shown signed out on Google's sign-in page: a profile that is still signed in is checked, and exported, with nobody watching, and an account notice of a signed-in profile ends the window instead of showing it. Ctrl+V (Cmd+V) types the clipboard's text into the window (a small add-on to noVNC's viewer from signin-window, the library the sign-in window and its links are built on; up to 1000 characters the window's keyboard has, which covers ASCII); on a phone, noVNC's keyboard button opens the phone's keyboard.

• Once Google Photos shows a signed-in account, the window checks that this account may use it (its bound address, or any address no other account here serves), then writes the snapshot from the same browser, as photos-mcp-session browser export does (it loads the library and opens one photo, so the library must not be empty), and closes. The server then binds the account to that address (also when the person closed the page meanwhile). A refused further-account sign-in removes its login profile. A refused default attempt discards only its private candidate and preserves accepted native state.

• The further-account keeper opens each signed-in profile every hour (PHOTOS_LOGIN_REFRESH_SECONDS) and writes a fresh snapshot, so Google's rotating cookies stay current. Only the browser decides that a session ended, and only on evidence seen on two refreshes in a row: Google's sign-in page, its signed-out page or a request to prove it is them again. Then the snapshot is withdrawn, and the person's next call says not_signed_in (a new link). Another Google account in the profile withdraws it at once. Anything else (an account notice, a slow page) keeps the snapshot and tries again after 10 minutes. When Google rejects a generation, the server asks the keeper to look again soon (at most every 5 minutes per account). The keeper never signs in: it holds no password. keeper.json beside each snapshot says what it last saw (photos_status: keeper).

• For the caller's account only. The tool returns the owner's permanent entry URL; there is no way to select another account. Only an explicit authenticated owner start creates/replaces an attempt, with at most 6 such starts per account an hour.

• One sign-in, 20 minutes. <PHOTOS_PUBLIC_URL>/connect/<id> identifies an attempt, with up to four explicit starts. Visiting a link opens no provider browser. Reloading or closing the page leaves an authenticated attempt available to resume; Cancel closes a waiting window. Saving continues independently of the page. A newer link replaces the previous one, and the connections screen checks the saved snapshot after a restart.

• Owner checks cover every route, including state, cancellation, noVNC assets and the ongoing WebSocket. Sessions are opaque server-side references, expire within 15 minutes and retain no provider OAuth tokens. Wrong users and expired sessions receive no account details; signing out also closes their existing viewer. POST and WebSocket requests require the exact public Origin. Pages are not cached and capability URLs are not sent as referrers.

• Your proxy routes only the UI exceptions. Forward /connections/, its exact login, callback, status, start, disconnect and logout children, and the existing /connect/<id> shapes without injecting a backend bearer. Keep /mcp behind the existing MCP admission policy. The application validates its own browser identity; proxy identity headers cannot create a browser session. Preserve Cookie, Set-Cookie, Origin and WebSocket upgrades and the configured public path prefix.

• Disconnect blocks application access first, fences old attempts, then drains work. Further-account login profiles/snapshots are deleted; the default's native profile and snapshot stay behind the durable barrier. Uncertain cleanup remains blocked across a restart and offers Retry disconnect. Reconnecting requires a fresh explicit start and the same bound Google address. Logging out leaves the saved provider connection alone.

Login service settings: PHOTOS_LOGIN_TOKEN (required), PHOTOS_LOGIN_PROFILES (/profiles), PHOTOS_LOGIN_SESSIONS (/sessions), PHOTOS_LOGIN_MINUTES (20, a window's time), PHOTOS_LOGIN_REFRESH_SECONDS (3600), PORT (8080), PHOTOS_LOGIN_UNMANAGED_BROWSER (see above). Its API (behind the bearer) never returns a session; /health is open. Before starting the Compose example, prepare ./state (scope reader), ./profiles (scope login) and ./maintenance (scope maintenance) using deployment setup. Each root must be owned by its container's application UID, have mode 0700 and contain the four 0600 deployment records. Set the container user or directory ownership to match; do not let Docker create these bind-mount roots as root-owned directories. Preserve existing records during upgrades, including holds and work tickets.

As a Compose file, beside the server:

services:
  photos-mcp:
    image: ghcr.io/benjamin-di/google-photos-mcp:latest
    read_only: true
    volumes:
      - ./session:/session:ro          # the default account's snapshot
      - ./state:/state
      - ./sessions:/sessions:ro        # the further accounts' snapshots
    environment:
      MCP_BEARER_TOKEN: ${PROXY_TOKEN}           # held by the authenticating proxy only
      GOOGLE_PHOTOS_EXPECTED_EMAIL: you@example.com
      PHOTOS_TRUSTED_ACCOUNT_HEADER: X-Account   # set by the proxy, never by clients
      PHOTOS_PUBLIC_URL: https://example.com/photos
      PHOTOS_LOGIN_URL: http://photos-mcp-login:8080
      PHOTOS_DEFAULT_LOGIN_URL: http://photos-default-login:8081
      PHOTOS_LOGIN_TOKEN: ${LOGIN_TOKEN}
      PHOTOS_CONNECTIONS_ISSUER: https://identity.example.com
      PHOTOS_CONNECTIONS_CLIENT_ID: photos-ui
      PHOTOS_CONNECTIONS_GROUP: photos-users
      PHOTOS_CONNECTIONS_ACCOUNT_CLAIM: account_alias
    networks: [default, login]
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"]
  photos-mcp-login:
    image: ghcr.io/benjamin-di/google-photos-mcp-login:latest
    read_only: true
    shm_size: 512m
    tmpfs: [/tmp, /home/login]
    volumes:
      - ./profiles:/profiles           # each account's Google sign-in: keep it private
      - ./sessions:/sessions
    environment:
      PHOTOS_LOGIN_TOKEN: ${LOGIN_TOKEN}
    networks: [login]                  # plus a network that reaches Google
  photos-default-login:
    image: ghcr.io/benjamin-di/google-photos-mcp-login:latest
    command: ["python", "-m", "photos_maintenance.human"]
    read_only: true
    shm_size: 512m
    tmpfs: [/tmp, /home/login]
    volumes:
      - ./maintenance:/maintenance     # the native profile and its existing lease
      - ./session:/export              # the same default snapshot read by the server
      - ./state/connections:/connections-controls
    environment:
      PHOTOS_LOGIN_TOKEN: ${LOGIN_TOKEN}
      PHOTOS_DEFAULT_LOGIN_ACCOUNT: default
      PHOTOS_DEFAULT_LOGIN_ROOT: /maintenance
      PHOTOS_DEFAULT_LOGIN_EXPORT_DIR: /export
      PHOTOS_DEFAULT_LOGIN_CONTROLS_DIR: /connections-controls
      PHOTOS_DEFAULT_LOGIN_EXPECTED_EMAIL: you@example.com
    depends_on:
      photos-mcp:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8081/health"]
    networks: [login]                  # plus a network that reaches Google
networks:
  login: {}

The example default custodian runs the human service alone. If native credential maintenance already owns the default profile, run both processes in that existing custodian's container and PID namespace, under one supervisor; retain its absolute paths, locks, holds and attempt ledger. Never copy a running browser profile. The reader must initialize its private controls before the custodian starts.

Operations

Use My connections' Disconnect to block new account operations immediately and retain that barrier across restart. The default's accepted profile/snapshot remain private; further-account login state is removed. For provider-wide revocation, use Google's account security settings separately. Privileged local operators can stop the server or remove a further account with admin account remove <id>; preserve current durable controls through recovery. These actions do not revoke an agent's gateway grant.

Development

make bootstrap, then make check (ruff, format, lock consistency, pytest; see AGENTS.md). make lock after changing dependencies in pyproject.toml. Tests never reach Google.

Recorded fixtures: python -m photos_mcp.capture OUT_DIR [--query Q] (scripts/capture-fixtures is the same entry point) records anonymised real answers through the normal transport, budgets and breaker, including the no-cookie signed-out answer. Run it with the server's configuration and state directory (for example docker exec photos-mcp python -m photos_mcp.capture /state/recorded; both keep budgets and the breaker in state.json, so keep the run short), review the output, check it in under tests/fixtures/recorded/ (tests/test_recorded.py and tests/test_fixture_privacy.py pick it up), then delete the output directory. The anonymiser replaces every string and every number about the account (see capture.py).

Layout: src/photos_mcp/ — server.py (tools, transports, the account registry), client.py (tool logic, paging, thumbnails), transport.py (HTTP policy), session.py (snapshot reader, cookies), session_export.py (photos-mcp-session), state.py (budgets, breaker), accounts.py (further accounts), connect.py (sign-in links, on signin-window's relay), login_client.py (the login service's API: signin-window's client plus the account routes), admin.py, config.py (settings), errors.py (error codes), cursors.py, cache.py, images.py, rpc.py (response parsers), capture.py (recorded fixtures), auth.py, logs.py, vendor/gpwc/ (request framing, read payloads). src/photos_login/ — the login service, on signin-window's: app.py (API), windows.py (the sign-in window's runner), window.py (the browser), keeper.py, profiles.py. docs/PAYLOADS.md maps every RPC and field path to its source. scripts/login_e2e.py checks sign-in links end to end with real browsers and a stand-in page (the release runs it in the login image).

Contributions: see CONTRIBUTING.md. Report security problems privately as described in SECURITY.md, not in public issues.

Licence and provenance

MIT (LICENSE). Based on vsmelov/google-photos-mcp, used under the MIT licence with its author's permission; vendors a modified subset of gpwc and derives its parser fixtures from Google-Photos-Toolkit, both MIT. See NOTICE and THIRD_PARTY_NOTICES.

Optional operator-owned account upkeep is documented in Account maintenance.