Google Photos

This MCP server lets Claude and other MCP clients access and search your Google Photos library in read-only mode. You can search photos by text, view albums, fetch photo details, and obtain approximate location data derived from descriptions, all through a lightweight, protocol-driven interface.

How to use

Use this server with an MCP client to search and retrieve photos, albums, and metadata from your Google Photos library. Start the server in STDIO mode for Claude Desktop to connect without a port, or use HTTP/URL mode for Cursor IDE and other MCP clients. Authentication happens once per development session and is stored locally for subsequent runs.

When you connect with Claude Desktop in STDIO mode, configure the MCP server to point to the local dist/index.js file and pass the STDIO flag. When using Cursor IDE in HTTP mode, point the client to the local HTTP endpoint to browse and query your photos.

How to install

Prerequisites: install Node.js 18 or newer and ensure you have access to a Google account with Google Photos enabled.

1. Clone the project directory.

2. Install dependencies to fetch TypeScript tooling and build helpers.

3. Create a configuration file with your Google Cloud credentials and redirect URI.

4. Build the server to generate the distributable files.

5. Start the server, authenticate with Google Photos, and then switch to the desired transport mode (STDIO for Claude Desktop or HTTP for Cursor IDE).

Configuration and usage notes

Important authentication flow: you must run the server in HTTP mode first to complete the Google OAuth flow, then switch to STDIO mode for Claude Desktop usage. The tokens are stored locally and persist across restarts.

Security note: CORS middleware has been removed to reduce exposure to cross-origin attacks. STDIO mode remains unaffected, while browser-based clients may encounter CORS errors.

Port and redirect configuration: you can run on a custom port and must update the redirect URI accordingly. For example, set PORT=3001 and use GOOG​LE_REDIRECT_URI=http://localhost:3001/auth/callback.

Troubleshooting and tips

If you encounter permission errors, verify Google Cloud project API access, OAuth credentials in your .env file, and that you completed the /auth flow. API changes in 2025 may limit photo access to app-created content; consider using the Photos Picker API for full library access.

If you need to test endpoints without a client, use the MCP Inspector to verify authentication and endpoint behavior before connecting Claude Desktop or Cursor IDE.

Usage with Claude Desktop

Use STDIO mode for Claude Desktop to simplify the local workflow and avoid port configuration. The server will communicate through standard I/O streams instead of network sockets.

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

Usage with Cursor IDE

If you are using Cursor IDE, you can run the server in HTTP mode or use a local URL endpoint. The HTTP URL is typically http://localhost:3000/mcp and you can also start the server with a node command pointing to the built distribution.

{
  "mcpServers": {
    "google_photos_http": {
      "type": "http",
      "name": "google_photos",
      "url": "http://localhost:3000/mcp",
      "args": []
    }
  }
}

Available tools

search_photos

Search for photos by text queries across filenames, descriptions, timestamps, and location data, with pagination support.

search_photos_by_location

Search for photos by location name and return matching items with optional pagination.

get_photo

Retrieve a specific photo by ID, with optional base64-encoded data and location metadata.

get_photo_url

Fetch a photo URL for a given ID with size options (s, m, l, d).

list_albums

List all albums with pagination options.

get_album

Retrieve a specific album by its ID.

list_album_photos

List photos within a specific album with optional location data and pagination.