Google Photos MCP Server
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.
Capacidad | Estado | API |
Explorar toda la biblioteca de fotos | ✅ | API de Selector |
Buscar fotos por texto/fecha/categoría | ✅ | API de la Biblioteca |
Crear álbumes y subir fotos | ✅ | API de la Biblioteca |
Acceder a contenido creado por la aplicación | ✅ | API de la Biblioteca |
Cómo funciona la API de Selector
Llama a
create_picker_session: devuelve una URL que el usuario abre en su navegadorEl usuario selecciona fotos de su biblioteca completa
Llama a
poll_picker_session: cuandomediaItemsSetes verdadero, se devuelven las fotos seleccionadas
Related MCP server: Immich MCP Server
🛡️ 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
Ve a Google Cloud Console
Crea un nuevo proyecto (o selecciona uno existente)
Habilita la API de la Biblioteca de Fotos
Crea credenciales de OAuth 2.0 (aplicación web)
Añade
http://localhost:3000/auth/callbackcomo URI de redirección autorizadaAnota 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 install3. Configuración
cp .env.example .envEdita .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=development4. 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 reload5. Autenticación
Inicia en modo HTTP:
npm startVisita
http://localhost:3000/authen tu navegadorCompleta el flujo de OAuth de Google
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 matchConfiguració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 cursorInspector MCP
npx @modelcontextprotocol/inspector node dist/index.js # HTTP
npx @modelcontextprotocol/inspector node dist/index.js --stdio # STDIOHerramientas disponibles (19)
Buscar y explorar
Herramienta | Descripción |
| Búsqueda de fotos basada en texto |
| Búsqueda por nombre de ubicación |
| Filtrar por fechas, categorías, tipo de medio, favoritos, archivados |
| Obtener detalles de la foto (base64 opcional) |
| Listar todos los álbumes |
| Obtener detalles del álbum |
| Listar fotos en un álbum |
| Listar todos los elementos multimedia |
| Referencia JSON de todas las opciones de filtro |
Escribir y gestionar
Herramienta | Descripción |
| Crear un nuevo álbum |
| Subir un archivo local |
| Añadir elementos existentes a un álbum (máx. 50) |
| Crear álbum + subir archivos en una sola llamada (máx. 50) |
| Añadir enriquecimiento de texto o ubicación |
| Establecer foto de portada del álbum |
API de Selector
Herramienta | Descripción |
| Iniciar una sesión de Selector para acceso completo a la biblioteca |
| Comprobar el estado de la sesión y recuperar fotos seleccionadas |
Autenticación
Herramienta | Descripción |
| Comprobar el estado de la autenticación |
| Iniciar el flujo de OAuth a través de 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, 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 seto la autenticación falla, verifica que tu archivo.envesté presente en el directorio raíz y contenga tus credenciales correctas de Google Cloud. Recuerda ejecutarnpm 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 templatesPruebas
npm test # All tests (Vitest)
npm run test:watch # Interactive TDD
npm run test:coverage # Coverage report
npm run test:security # Security suite onlyControles de calidad
Los tres deben aprobarse antes de la fusión:
npx tsc --noEmit # Type check
npm run lint # ESLint
npm test # TestsLicencia
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search photos and video moments by visual meaning, people, dates, and folders across local libraries, Apple Photos, and OneDrive. Manage collections, groups, favorites, people, and duplicate review. Synced metadata remains searchable while the desktop is offline; local and Apple Photos media access needs the owning device online with remote access enabled. OneDrive media can be accessed directly from the cloud. OAuth or Bearer API keys. Paid Cloud Access required; hosted visual search uses prepaid credits. Text-in-image search is semantic matching, not guaranteed exact OCR. Setup: https://organizewith.ai/en/guides/connect-ai-assistants
Sort, search and tidy your Google Photos from chat: find photos and videos, read their details, dow…
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Remote streamable-HTTP MCP server running on a single Cloudflare Worker. Your assistant gets live Airbnb, Amazon, Booking.com, Google Flights, Maps and Reddit data, social search on X, Instagram and TikTok, the Meta Ad Library, and image/video generation without any keys. Connect your own accounts to let it send WhatsApp or Telegram messages, work an IMAP inbox, manage Meta Ads campaigns and publish to X and LinkedIn. OAuth 2.1 with PKCE; stored credentials are AES-256-GCM encrypted.
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceExposes a visual library with semantic search, tagging, editing, and management of photos as tools for AI agents like Claude Code.13 npm49MIT- FlicenseNot gradedqualityCmaintenanceEnables users to search and retrieve photos from a self-hosted Immich photo library via natural language, supporting CLIP-based semantic search, metadata filtering, album browsing, and share link creation.-
- AlicenseAqualityBmaintenanceEnables AI agents to search, inspect, organize, and export photos from a local Apple Photos library using natural language, including scene labels, text, faces, places, and albums.131MIT
- AlicenseAqualityBmaintenanceEnables AI agents to work with a user's Google Photos through Google's picker, letting users choose exactly what the agent sees while providing tools for uploading media, creating and sharing albums, writing captions and enrichments, searching app-created media, and managing multiple Google accounts.2948 npm1MIT