Google Photos MCP Server

A Model Context Protocol (MCP) server for Google Photos integration, enabling Claude, Gemini, and other AI assistants to read, write, and pick photos from your Google Photos library.

✅ Picker API Support (March 2025+)

This server implements the Google Photos Picker API, providing full library access even after the March 31, 2025 deprecation of certain Library API scopes.

Capability	Status	API
Browse full photo library	✅	Picker API
Search photos by text/date/category	✅	Library API
Create albums & upload photos	✅	Library API
Access app-created content	✅	Library API

How the Picker API Works

Call create_picker_session — returns a URL the user opens in their browser
User selects photos from their full library
Call poll_picker_session — when mediaItemsSet is true, selected photos are returned

🛡️ Security Notice: CORS Removed

CORS middleware has been removed for security (prevents drive-by attacks on localhost).

✅ STDIO mode (Claude Desktop): Works normally
✅ Streamable HTTP (Cursor, server-to-server): Works normally
❌ Browser AJAX: Not supported (by design)

Features

Read Operations

Search photos by text, date, location, category, favorites
Filter by media type (photo/video), date ranges, archived status
Get photo details including base64-encoded images
List albums and their contents
Describe available filter capabilities

Write Operations

Create albums and upload photos
Batch upload with create_album_with_media (up to 50 files)
Add text and location enrichments to albums
Set album cover photos

Picker Operations

Create picker sessions for full library access
Poll sessions and retrieve selected media items

Infrastructure

⚡ Streamable HTTP transport (MCP 2025-06-18 spec)
🔗 HTTPS Keep-Alive with connection pooling
🔒 OS keychain token storage
📊 Quota management with automatic tracking
🔄 Automatic token refresh

Prerequisites

Node.js 18+
Google Cloud project with Photos Library API enabled
OAuth 2.0 credentials (Web application type)

Setup

1. Google Cloud Setup

Go to Google Cloud Console
Create a new project (or select existing)
Enable Photos Library API
Create OAuth 2.0 credentials (Web application)
Add http://localhost:3000/auth/callback as an authorized redirect URI
Note your Client ID and Client Secret

2. Installation

git clone https://github.com/savethepolarbears/google-photos-mcp.git
cd google-photos-mcp
npm install

3. Configuration

cp .env.example .env

Edit .env:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
PORT=3000
NODE_ENV=development

4. Build & Run

npm run build    # Compile TypeScript
npm start        # HTTP mode (for auth & Cursor)
npm run stdio    # STDIO mode (for Claude Desktop)
npm run dev      # Dev mode with live reload

5. Authenticate

Start in HTTP mode: npm start
Visit http://localhost:3000/auth in your browser
Complete the Google OAuth flow
Tokens are saved automatically to the OS keychain

Note: Authentication must be completed in HTTP mode first. After that, switch to STDIO mode for Claude Desktop.

Dynamic Port

PORT=3001 npm start
# Also update GOOGLE_REDIRECT_URI in .env to match

Client Configuration

Claude Desktop (STDIO)

{
  "mcpServers": {
    "google-photos": {
      "command": "node",
      "args": ["/path/to/google-photos-mcp/dist/index.js", "--stdio"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:3000/auth/callback"
      }
    }
  }
}

Cursor IDE

STDIO (recommended):

Type: Command
Command: node /path/to/google-photos-mcp/dist/index.js --stdio

HTTP:

Type: URL
URL: http://localhost:3000/mcp

Smithery

# Claude Desktop
npx -y @smithery/cli install google-photos-mcp --client claude

# Cursor IDE
npx -y @smithery/cli install google-photos-mcp --client cursor

MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js        # HTTP
npx @modelcontextprotocol/inspector node dist/index.js --stdio # STDIO

Available Tools (19)

Search & Browse

Tool	Description
`search_photos`	Text-based photo search
`search_photos_by_location`	Search by location name
`search_media_by_filter`	Filter by dates, categories, media type, favorites, archived
`get_photo`	Get photo details (optional base64)
`list_albums`	List all albums
`get_album`	Get album details
`list_album_photos`	List photos in an album
`list_media_items`	List all media items
`describe_filter_capabilities`	JSON reference of all filter options

Write & Manage

Tool	Description
`create_album`	Create a new album
`upload_media`	Upload a local file
`add_media_to_album`	Add existing items to an album (max 50)
`create_album_with_media`	Create album + upload files in one call (max 50)
`add_album_enrichment`	Add text or location enrichment
`set_album_cover`	Set album cover photo

Picker API

Tool	Description
`create_picker_session`	Start a Picker session for full library access
`poll_picker_session`	Check session status and retrieve selected photos

Auth

Tool	Description
`auth_status`	Check authentication status
`start_auth`	Start OAuth flow via temporary local server

Example Queries

"Show me photos from my trip to Paris"
"Find photos of my dog from 2024"
"List my photo albums"
"Upload these vacation photos to a new album called 'Summer 2025'"
"Search for landscape photos from last year, ordered newest first"
"Let me pick some photos from my library" (triggers Picker API)

Location Data

Location data is approximate, extracted from photo descriptions using OpenStreetMap/Nominatim geocoding. When available, includes latitude/longitude, city, region, country.

Development

Project Structure

src/
├── index.ts              # HTTP entry point
├── dxt-server.ts         # STDIO/DXT entry point
├── mcp/core.ts           # All tool handlers (19 tools)
├── api/
│   ├── client.ts         # REST client (Library + Picker)
│   ├── photos.ts         # Facade module (re-exports)
│   ├── types.ts          # TypeScript interfaces
│   └── repositories/     # Low-level API calls
├── auth/                 # OAuth, tokens, keychain
├── schemas/              # Zod validation schemas
├── utils/                # Config, logging, quota, retry
└── views/                # HTML templates

Testing

npm test              # All tests (Vitest)
npm run test:watch    # Interactive TDD
npm run test:coverage # Coverage report
npm run test:security # Security suite only

Quality Checks

All three must pass before merge:

npx tsc --noEmit   # Type check
npm run lint        # ESLint
npm test            # Tests

License

MIT

Google Photos