Search, browse, and retrieve metadata and images from your Google Photos library.
Google Photos MCP Server
A Model Context Protocol (MCP) server for Google Photos integration, allowing Claude and other AI assistants to access and work with your Google Photos library.
⚠️ Important Notice: 2025 Google Photos API Changes
As of March 31, 2025, Google Photos API access is limited to app-created content only. This MCP server may have limited functionality with your existing photos. For full library access, Google now recommends using the Photos Picker API.
🛡️ Security Notice: CORS Removed (December 2025)
Breaking Change: CORS middleware has been removed for security reasons (commit 8afc1e2).
Why: The previous permissive CORS configuration exposed localhost users to drive-by attacks from malicious websites.
Impact:
- ✅ STDIO mode (Claude Desktop): No impact - continues to work normally
- ✅ SSE mode (Cursor IDE): No impact for same-origin requests
- ❌ Browser-based clients: Will encounter CORS errors
Supported Use Cases:
- Claude Desktop (STDIO transport) - Recommended
- Cursor IDE (SSE transport)
- Server-to-server MCP clients
Not Supported:
- Direct browser AJAX calls from web applications
- Cross-origin browser requests
For technical details, see .jules/sentinel.md.
⚡ Performance & Modern Protocol Support
Streamable HTTP Transport (December 2025)
Upgraded to Streamable HTTP transport (2025-06-18 MCP specification):
- ✅ SSE transport deprecated and removed
- ✅ Modern session-based protocol with proper lifecycle management
- ✅ Supports incremental results and bidirectional communication
- ✅ Production-ready for networked MCP deployments
HTTPS Keep-Alive (December 2025)
The Google Photos API client uses persistent HTTPS connections (Keep-Alive) for performance:
- Reduces latency by reusing TCP connections (30-50ms per request)
- Connection pooling: Max 50 concurrent connections, keeps 10 idle connections warm
- Particularly beneficial for operations with multiple API calls (pagination, location enrichment)
- Automatically managed - no user configuration required
Technical Details: Configured with 30s keep-alive probes, 60s idle timeout, optimized for Google Photos API quota limits.
Port Configuration
Dynamic port support via environment variable:
# Run on custom port (avoids conflicts with other dev servers)
PORT=3001 npm start
# Or set in .env file:
PORT=3001
Important: If you change PORT, also update GOOGLE_REDIRECT_URI in .env to match:
GOOGLE_REDIRECT_URI=http://localhost:3001/auth/callback
Recommended for Claude Desktop: Use STDIO mode instead (no port needed):
npm run stdio
Features
- ✅ Search photos by content, date, location
- ✅ Get location data for photos (approximate, based on descriptions)
- ✅ Fetch specific photos by ID
- ✅ List albums and photo collections
- ✅ Retrieve photo metadata and base64-encoded images
- ✅ Proper STDIO mode support for Claude Desktop
- ✅ Enhanced error handling and 2025 API compatibility warnings
- ✅ Works with Claude Desktop, Cursor IDE, and other MCP-compatible clients
API Limitations (Google Photos API)
What This MCP CAN Do:
- ✅ Search and browse photos (read-only access)
- ✅ Get photo details, metadata, and images
- ✅ List albums and their contents
- ✅ Extract location information from descriptions
What This MCP CANNOT Do:
- ❌ Delete photos or albums (API does not support deletion)
- ❌ Upload new photos (beyond scope of this MCP)
- ❌ Modify photo metadata or descriptions
- ❌ Create or manage albums
- ❌ Access precise GPS/EXIF coordinates (API limitation)
Why: The Google Photos Library API provides read-only access. Photo deletion, uploads, and metadata editing must be done through the Google Photos web or mobile app.
Text search behavior
- Search queries are tokenized on whitespace/
:and compared against photo filenames, descriptions, timestamps, and any cached location metadata. - Tokens that do not appear in any searchable fields are ignored so that queries like
vacation 2023still surface "vacation" matches even when the year is missing from the metadata. - When none of the tokens match, the server falls back to the Google Photos API response instead of returning an empty result set, preserving the original ordering for broad or unmatched queries.
Prerequisites
- Node.js 18 or newer
- Google account with access to Google Photos
- Google Cloud project with Photos Library API enabled
Setup
1. Google Cloud Setup
- Go to Google Cloud Console
- Create a new project
- Navigate to "APIs & Services" > "Library"
- Search for and enable "Photos Library API"
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Select "Web application" as the application type
- Add
http://localhost:3000/auth/callbackas an authorized redirect URI - Note your Client ID and Client Secret
2. Instal
Tools (4)
search_photosSearch photos by content, date, or location using tokenized queries.list_albumsRetrieve a list of photo albums and collections from the library.get_photoFetch a specific photo by its unique ID, including metadata and base64 data.get_location_dataExtract approximate location data for photos based on descriptions.Environment Variables
GOOGLE_CLIENT_IDrequiredOAuth 2.0 Client ID from Google Cloud ConsoleGOOGLE_CLIENT_SECRETrequiredOAuth 2.0 Client Secret from Google Cloud ConsoleGOOGLE_REDIRECT_URIrequiredAuthorized redirect URI (e.g., http://localhost:3000/auth/callback)PORTDynamic port for HTTP/SSE transportConfiguration
{"mcpServers":{"google-photos":{"command":"npx","args":["-y","@savethepolarbears/google-photos-mcp"],"env":{"GOOGLE_CLIENT_ID":"your_client_id","GOOGLE_CLIENT_SECRET":"your_client_secret","GOOGLE_REDIRECT_URI":"http://localhost:3000/auth/callback"}}}}