npm package: @iflow-mcp/savethepolarbears-google-photos-mcp
Description: MCP server for Google Photos integration with Claude
Latest version: 0.1.0

# 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:
```bash
# 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):
```bash
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 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](https://console.cloud.google.com/)
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
   ```bash
   git clone https://github.com/savethepolarbears/google-photos-mcp.git
   cd google-photos-mcp
   ```

2. **Install dependencies** (⚠️ Required before building):
   ```bash
   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:
   ```bash
   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:
   ```bash
   npm run build
   ```
   This compiles TypeScript to JavaScript in the `dist/` directory.
5. Start the server:
   ```bash
   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:
   ```bash
   # 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:
   ```bash
   npm run stdio
   ```

3. In Claude Desktop, add the MCP server:
   - Go to Settings > MCP Servers
   - Select "Edit Config"
   - Add the following configuration:

   ```json
   {
     "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:
   ```bash
   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](https://smithery.ai/) 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:

```bash
npx -y @smithery/cli install google-photos-mcp --client claude
```

### For Cursor IDE:

```bash
npx -y @smithery/cli install google-photos-mcp --client cursor
```

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

```yaml
name: google-photos-mcp
displayName: Google Photos
description: Access and search your Google Photos library through MCP
logo: https://raw.githubusercontent.com/savethepolarbears/google-photos-mcp/main/logo.png
repository: https://github.com/savethepolarbears/google-photos-mcp
keywords:
  - google photos
  - images
  - albums
  - photos
  - search
```

## 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:

```bash
npm run build
```

### Linting

To check for linting errors, run:

```bash
npm run lint
```

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