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:

Important: If you change PORT, also update GOOGLE_REDIRECT_URI in .env to match:

Recommended for Claude Desktop: Use STDIO mode instead (no port needed):

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 2023 still 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

1. Go to Google Cloud Console

2. Create a new project

3. Navigate to "APIs & Services" > "Library"

4. Search for and enable "Photos Library API"

5. Go to "APIs & Services" > "Credentials"

6. Click "Create Credentials" > "OAuth client ID"

7. Select "Web application" as the application type

8. Add http://localhost:3000/auth/callback as an authorized redirect URI

9. Note your Client ID and Client Secret

2. Installation

1. Clone this repository

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

2. Install dependencies (⚠️ Required before building):

   npm install

   Note: This installs TypeScript and other build tools. If you get tsc: command not found errors, ensure this step completed successfully.

3. Create a .env file with your Google Cloud credentials:

   cp .env.example .env # Edit .env with your credentials
   GOOGLE_CLIENT_ID=your_client_id_here GOOGLE_CLIENT_SECRET=your_client_secret_here GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback PORT=3000 NODE_ENV=development

4. Build the server:

   npm run build

   This compiles TypeScript to JavaScript in the dist/ directory.

5. Start the server:

   npm start

6. Authenticate with Google Photos:

   • Visit http://localhost:3000 in your browser

   • Click "Authenticate with Google Photos"

   • Follow the Google OAuth flow to grant access to your photos

Important Authentication Notes

⚠️ Authentication must be done in HTTP mode first!

Before using this MCP server with Claude Desktop or other STDIO-based clients:

1. First run the server in HTTP mode: npm start

2. Complete the authentication at http://localhost:3000/auth

3. Only after successful authentication, stop the server and switch to STDIO mode for Claude Desktop

The authentication tokens are stored locally and will persist between server restarts.

Testing with MCP Inspector

The MCP Inspector is an interactive developer tool for testing and debugging MCP servers. It allows you to verify your server's functionality before integrating it with clients like Claude or Cursor.

1. Install and run the MCP Inspector with your server:

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

2. The Inspector will open a web interface (typically at http://localhost:6274) where you can:

   • Test all available tools

   • Verify authentication works correctly

   • Inspect request/response payloads

   • Debug any issues with your server

This step is highly recommended before integrating with Claude Desktop or other clients to ensure your server is working correctly.

Usage with Claude Desktop

To use this MCP server with Claude Desktop:

1. Ensure you have authenticated first (see Authentication Notes above)

2. Start the server in STDIO mode:

   npm run stdio

3. In Claude Desktop, add the MCP server:

   • Go to Settings > MCP Servers

   • Select "Edit Config"

   • Add the following configuration:

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

4. Save the configuration and restart Claude Desktop

5. You can now ask Claude to search and fetch photos from your Google Photos account

Usage with Cursor IDE

To use this MCP server with Cursor IDE:

1. Start the server in HTTP mode:

   npm start

2. In Cursor IDE, configure the MCP server:

   • Open the MCP panel in Cursor

   • Click "Add Server"

   • Choose "Command" as the Type

   • Enter the following for Command: node /path/to/your/project/dist/index.js

   • Name it "Google Photos"

   • Click "Save"

Alternatively, for HTTP mode:

• Choose "URL" as the Type

• Enter the server URL: http://localhost:3000/mcp

• Name it "Google Photos"

• Click "Save"

Troubleshooting

JSON Parsing Errors in STDIO Mode (Issue #2)

Fixed in latest version! If you're getting errors like "Unexpected token 'S', 'Server run'..." when using the MCP Inspector:

1. Make sure you're using the latest version of this server

2. The issue was caused by console output going to stdout instead of stderr in STDIO mode

3. All logging now properly goes to stderr when using --stdio flag

Authentication Endpoint Not Working (Issue #1)

Fixed in latest version! The /auth endpoint and HTML page are now properly configured:

1. Start the server in HTTP mode: npm start

2. Visit http://localhost:3000/auth in your browser

3. Follow the Google OAuth flow

4. After authentication, switch to STDIO mode for Claude Desktop usage

Limited Photo Access (2025 API Changes)

Due to Google Photos API changes effective March 31, 2025:

1. Expected behavior: You may only see limited photos (app-created content)

2. This is not a bug: Google has restricted API access to app-created content only

3. Solution: For full photo library access, Google recommends using the Photos Picker API

4. Current workaround: This server still works but with limited scope

Permission Denied Errors

If you get 403 PERMISSION_DENIED errors:

1. Check that your Google Cloud project has the Photos Library API enabled

2. Verify your OAuth credentials are correct in the .env file

3. Make sure you've completed the authentication flow via /auth

4. Note: Due to 2025 API changes, some functionality may be limited

Integration with Smithery

Smithery is a registry for MCP servers that makes it easy to discover and install various MCP tools. You can register your Google Photos MCP server with Smithery to make it available to the community.

To install the Google Photos MCP server from Smithery:

For Claude Desktop:

For Cursor IDE:

You can also add a smithery.yaml file to your repository with the following content to make it discoverable:

Available Tools

Search Tools

• search_photos: Search for photos based on text queries

  Parameters: - query: string (e.g., "vacation 2023", "sunset photos", "cats") - pageSize: number (optional, default: 25) - pageToken: string (optional, for pagination) - includeLocation: boolean (optional, default: true)

  Text queries are applied to filenames, descriptions, timestamps, and available location metadata. Tokens that do not appear in any searchable field are ignored so that stop-words or date fragments do not filter out valid items, and if metadata filteri ng would otherwise remove every item returned by Google Photos the original API response is preserved.

• search_photos_by_location: Search for photos based on location

  Parameters: - locationName: string (e.g., "Paris", "Central Park", "Mount Everest") - pageSize: number (optional, default: 25) - pageToken: string (optional, for pagination)

Photo Tools

• get_photo: Get a specific photo by ID

  Parameters: - photoId: string - includeBase64: boolean (optional, default: false) - includeLocation: boolean (optional, default: true)

• get_photo_url: Get a specific photo URL with size options

  Parameters: - photoId: string - size: "s" | "m" | "l" | "d" (small, medium, large, original)

Album Tools

• list_albums: List all albums

  Parameters: - pageSize: number (optional, default: 20) - pageToken: string (optional, for pagination)

• get_album: Get a specific album by ID

  Parameters: - albumId: string

• list_album_photos: List photos in a specific album

  Parameters: - albumId: string - pageSize: number (optional, default: 25) - pageToken: string (optional, for pagination) - includeLocation: boolean (optional, default: true)

Example Queries for Claude

Once your MCP server is set up and connected to Claude, you can ask queries like:

• "Show me photos from my trip to Paris"

• "Find photos of my dog"

• "Show me photos from last summer"

• "Get photos from my 'Family' album"

• "Show me landscape photos from 2023"

• "Find photos taken in Yellowstone National Park"

Location Data Support

The Google Photos API doesn't provide exact geolocation coordinates directly. This implementation attempts to extract location information from photo descriptions and uses geocoding to provide approximate location data when possible. Location features include:

• Extracting location information from photo descriptions

• Geocoding location names to obtain coordinates (using OpenStreetMap/Nominatim)

• Searching photos by location name

• Including location data in search results (when available)

Note that location data is approximate and may not be available for all photos.

Troubleshooting

If you encounter issues:

1. Verify your API credentials are correct in the .env file

2. Check the MCP server logs for error messages

3. Use the MCP Inspector to test the server directly

4. Ensure you've authorized the application with Google Photos

5. Try restarting the server and client application

Development

Building

To build the project, run:

Linting

To check for linting errors, run:

Documentation

The codebase is thoroughly documented using JSDoc/TSDoc comments. You can review the source code in src/ to understand the purpose and usage of functions, classes, and interfaces.

License

MIT