Google Photos

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

This server implements theGoogle Photos Picker API, providing full library access even after the March 31, 2025 deprecation of certain Library API scopes.
- Callcreate_picker_session— returns a URL the user opens in their browser
- User selects photos from their full library
- Callpoll_picker_session— whenmediaItemsSetis true, selected photos are returned

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)

- 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

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

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

- ⚡ 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

- Node.js 22.22+
- Google Cloud project withPhotos Library APIenabled
- OAuth 2.0 credentials (Web application type)
- Go toGoogle Cloud Console
- Create a new project (or select existing)
- EnablePhotos Library API
- Create OAuth 2.0 credentials (Web application)
- Addhttp://localhost:3000/auth/callbackas an authorized redirect URI
- Note your Client ID and Client Secret

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

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

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

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

{ "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" } } } }

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

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

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

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

"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 is approximate, extracted from photo descriptions using OpenStreetMap/Nominatim geocoding. When available, includes latitude/longitude, city, region, country.

This project is a Model Context Protocol (MCP) server intended to be run locally alongside AI clients like Claude Desktop or Cursor. There is no remote deployment or release process required beyond keeping your local checkout or NPM installation up to date.

- Node Version: Ensure you are using Node.js 22.22+ as older versions are not supported.
- Authentication: If you encounterGOOGLE_CLIENT_ID is not seterrors or authentication fails, verify your.envfile is present in the root directory and contains your correct Google Cloud credentials. Remember to runnpm start(HTTP mode) to authenticate before switching to STDIO mode.
- Quota Issues: Google Photos API limits apply. Ensure you aren't hitting the 10,000 requests/day quota limit. The server tracks this viaquotaManager.
- CORS Errors: The server intentionally disables CORS to prevent drive-by attacks. Do not attempt to call the server directly from browser AJAX requests.

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

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

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

Interact with the Intelligent Content Management platform through Box AI.

An MCP server for interacting with AIStor and MinIO object stores.

Access various storage services like S3, GCS, and Azure Blob through the Apache OpenDAL™ project, configured via environment variables.

Manage AWS S3 buckets and objects, including policies, tagging, and configurations.

Manage AWS S3 operations, providing secure access to S3 buckets through pre-signed URLs.

Upload images and videos to Cloudinary from compatible MCP clients.

DeFi agent definitions JSON API - Production-ready agents for Web3, crypto trading, portfolio management, and blockchain automation

GCP Bucket Connector (data-connectors-ai)

Read-only MCP server for GCP Cloud Storage: list objects in a bucket.

A server for backing up and restoring data for AI agents and code editing tools.

Uploads local images to Bilibili's image hosting service and returns a permanent HTTPS link.