Servidor MCP de Google Photos

Un servidor del Protocolo de Contexto de Modelos (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 para la API de Selector (marzo de 2025 en adelante)

Este servidor implementa la API de Selector de Google Photos, proporcionando acceso completo a la biblioteca incluso después de la retirada de ciertos alcances de la API de la Biblioteca el 31 de marzo de 2025.

Cómo funciona la API de Selector

1. Llama a create_picker_session: devuelve una URL que el usuario abre en su navegador

2. El usuario selecciona fotos de su biblioteca completa

3. Llama a poll_picker_session: cuando mediaItemsSet es verdadero, se devuelven las fotos seleccionadas

Related MCP server: CoreViz MCP

🛡️ Aviso de seguridad: CORS eliminado

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

• ✅ Modo STDIO (Claude Desktop): Funciona normalmente

• ✅ HTTP con streaming (Cursor, servidor a servidor): Funciona normalmente

• ❌ AJAX de 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 fecha, estado de archivado

• Obtener detalles de fotos, incluidas imágenes codificadas en base64

• Listar álbumes y su contenido

• Describir las capacidades de filtrado disponibles

Operaciones de escritura

• Crear álbumes y subir fotos

• Subida 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 álbum

Operaciones de selector

• Crear sesiones de selector para acceso completo a la biblioteca

• Sondear sesiones y recuperar elementos multimedia seleccionados

Infraestructura

• ⚡ Transporte HTTP con streaming (especificación MCP 2025-06-18)

• 🔗 HTTPS Keep-Alive con agrupación de conexiones

• 🔒 Almacenamiento de tokens en el llavero del SO

• 📊 Gestión de cuotas con seguimiento automático

• 🔄 Actualización automática de tokens

Requisitos previos

• Node.js 22.22+

• Proyecto de Google Cloud con la API de la Biblioteca de Fotos habilitada

• Credenciales de OAuth 2.0 (tipo aplicación web)

Configuración

1. Configuración de Google Cloud

1. Ve a Google Cloud Console

2. Crea un nuevo proyecto (o selecciona uno existente)

3. Habilita la API de la Biblioteca de Fotos

4. Crea credenciales de OAuth 2.0 (aplicación web)

5. Añade http://localhost:3000/auth/callback como URI de redirección autorizada

6. Anota tu ID de cliente y tu secreto de cliente

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. Compilación y ejecución

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

1. Inicia en modo HTTP: npm start

2. Visita http://localhost:3000/auth en tu navegador

3. Completa el flujo de OAuth de Google

4. Los tokens se guardan automáticamente en el llavero del SO

Nota: La autenticación debe completarse primero en modo HTTP. Después de eso, 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

Inspector MCP

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

Herramientas disponibles (19)

Buscar y explorar

Escribir y gestionar

API de Selector

Autenticación

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, extraídos 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.

Despliegue / lanzamiento

Este proyecto es un servidor del Protocolo de Contexto de Modelos (MCP) destinado a ejecutarse localmente junto a clientes de IA como Claude Desktop o Cursor. No se requiere ningún proceso de despliegue o lanzamiento remoto más allá de mantener actualizada tu instalación local o 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 a través de quotaManager.

• Errores de CORS: El servidor deshabilita intencionalmente CORS para evitar ataques de tipo 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 aprobarse antes de la fusión:

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

Licencia

MIT