Google Photos

Accede y gestiona tu biblioteca de Google Photos con asistentes de IA.

Documentación

Servidor MCP de Google Photos

Un servidor de Model Context Protocol (MCP) para la integración con Google Photos, que permite a Claude, Gemini y otros asistentes de IA leer, escribir y seleccionar fotos de tu biblioteca de Google Photos.

✅ Soporte de Picker API (marzo de 2025+)

Este servidor implementa la Google Photos Picker API, proporcionando acceso completo a la biblioteca incluso después de la desaprobación de ciertos alcances de Library API el 31 de marzo de 2025.

Capacidad	Estado	API
Explorar la biblioteca completa de fotos	✅	Picker API
Buscar fotos por texto/fecha/categoría	✅	Library API
Crear álbumes y subir fotos	✅	Library API
Acceder a contenido creado por la aplicación	✅	Library API

Cómo funciona la Picker API

Llama a create_picker_session — devuelve una URL que el usuario abre en su navegador
El usuario selecciona fotos de su biblioteca completa
Llama a poll_picker_session — cuando mediaItemsSet es verdadero, se devuelven las fotos seleccionadas

🛡️ Aviso de seguridad: CORS eliminado

El middleware de CORS se ha eliminado por seguridad (previene ataques drive-by en localhost).

✅ Modo STDIO (Claude Desktop): Funciona normalmente
✅ Streamable HTTP (Cursor, servidor a servidor): Funciona normalmente
❌ AJAX del navegador: No compatible (por diseño)

Características

Operaciones de lectura

Buscar fotos por texto, fecha, ubicación, categoría, favoritos
Filtrar por tipo de medio (foto/video), rangos de fechas, estado de archivado
Obtener detalles de fotos, incluidas imágenes codificadas en base64
Listar álbumes y su contenido
Describir las capacidades de filtro disponibles

Operaciones de escritura

Crear álbumes y subir fotos
Carga por lotes con create_album_with_media (hasta 50 archivos)
Añadir enriquecimientos de texto y ubicación a los álbumes
Establecer fotos de portada de álbumes

Operaciones de Picker

Crear sesiones de Picker para acceso completo a la biblioteca
Consultar sesiones y recuperar elementos multimedia seleccionados

Infraestructura

⚡ Transporte Streamable HTTP (especificación MCP 2025-06-18)
🔗 HTTPS Keep-Alive con agrupación de conexiones
🔒 Almacenamiento de tokens en el llavero del sistema operativo
📊 Gestión de cuotas con seguimiento automático
🔄 Renovación automática de tokens

Requisitos previos

Node.js 22.22+
Proyecto de Google Cloud con Photos Library API habilitada
Credenciales de OAuth 2.0 (tipo aplicación web)

Configuración

1. Configuración de Google Cloud

Ve a Google Cloud Console
Crea un nuevo proyecto (o selecciona uno existente)
Habilita Photos Library API
Crea credenciales de OAuth 2.0 (aplicación web)
Añade http://localhost:3000/auth/callback como URI de redirección autorizada
Anota tu Client ID y Client Secret

2. Instalación

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

3. Configuración

cp .env.example .env

Edita .env:

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

4. Compilar y ejecutar

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

5. Autenticación

Inicia en modo HTTP: npm start
Visita http://localhost:3000/auth en tu navegador
Completa el flujo de OAuth de Google
Los tokens se guardan automáticamente en el llavero del sistema operativo

Nota: La autenticación debe completarse primero en modo HTTP. Después, cambia al modo STDIO para Claude Desktop.

Puerto dinámico

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

Configuración del cliente

Claude Desktop (STDIO)

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

Cursor IDE

STDIO (recomendado):

Tipo: Comando
Comando: node /path/to/google-photos-mcp/dist/index.js --stdio

HTTP:

Tipo: URL
URL: http://localhost:3000/mcp

Smithery

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

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

MCP Inspector

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

Herramientas disponibles (19)

Búsqueda y exploración

Herramienta	Descripción
`search_photos`	Búsqueda de fotos por texto
`search_photos_by_location`	Búsqueda por nombre de ubicación
`search_media_by_filter`	Filtrar por fechas, categorías, tipo de medio, favoritos, archivado
`get_photo`	Obtener detalles de la foto (base64 opcional)
`list_albums`	Listar todos los álbumes
`get_album`	Obtener detalles del álbum
`list_album_photos`	Listar fotos en un álbum
`list_media_items`	Listar todos los elementos multimedia
`describe_filter_capabilities`	Referencia JSON de todas las opciones de filtro

Escritura y gestión

Herramienta	Descripción
`create_album`	Crear un nuevo álbum
`upload_media`	Subir un archivo local
`add_media_to_album`	Añadir elementos existentes a un álbum (máx. 50)
`create_album_with_media`	Crear álbum + subir archivos en una sola llamada (máx. 50)
`add_album_enrichment`	Añadir enriquecimiento de texto o ubicación
`set_album_cover`	Establecer foto de portada del álbum

Picker API

Herramienta	Descripción
`create_picker_session`	Iniciar una sesión de Picker para acceso completo a la biblioteca
`poll_picker_session`	Comprobar el estado de la sesión y recuperar las fotos seleccionadas

Autenticación

Herramienta	Descripción
`auth_status`	Comprobar el estado de autenticación
`start_auth`	Iniciar el flujo de OAuth mediante un servidor local temporal

Consultas de ejemplo

"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)

Datos de ubicación

Los datos de ubicación son aproximados y se extraen de las descripciones de las fotos mediante geocodificación de OpenStreetMap/Nominatim. Cuando están disponibles, incluyen latitud/longitud, ciudad, región y país.

Implementación / publicación

Este proyecto es un servidor de Model Context Protocol (MCP) diseñado para ejecutarse localmente junto con clientes de IA como Claude Desktop o Cursor. No se requiere ningún proceso de implementación o publicación remota más allá de mantener actualizada tu copia local o la instalación de NPM.

Solución de problemas

Versión de Node: Asegúrate de usar Node.js 22.22+, ya que las versiones anteriores no son compatibles.
Autenticación: Si encuentras errores de GOOGLE_CLIENT_ID is not set o la autenticación falla, verifica que tu archivo .env esté presente en el directorio raíz y contenga tus credenciales correctas de Google Cloud. Recuerda ejecutar npm start (modo HTTP) para autenticarte antes de cambiar al modo STDIO.
Problemas de cuota: Se aplican los límites de la API de Google Photos. Asegúrate de no alcanzar el límite de cuota de 10,000 solicitudes/día. El servidor realiza un seguimiento de esto mediante quotaManager.
Errores de CORS: El servidor desactiva intencionalmente CORS para prevenir ataques drive-by. No intentes llamar al servidor directamente desde solicitudes AJAX del navegador.

Desarrollo

Estructura del proyecto

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

Pruebas

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

Controles de calidad

Los tres deben pasar antes del merge:

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

Licencia

MIT