Immich Photo Manager
Gestión de fotos con IA para Immich, 94 herramientas, Immich 2.x y 3.x
El Problema
Tienes miles de fotos en Immich pero encontrar algo significa hacer scroll sin fin. La búsqueda se limita a metadatos básicos. Crear álbumes es manual y tedioso. Capturas de pantalla, duplicados y fotos borrosas llenan tu biblioteca. Un caos total.
La Solución
Dile a Claude lo que quieres en lenguaje natural. El servidor MCP hace el resto: búsqueda inteligente via CLIP y del texto dentro de las fotos, álbumes geográficos automáticos, limpieza asistida que recuerda cada veredicto, frames de cualquier vídeo y un fotolibro en PDF. Nunca borra sin preguntar.
¿Por qué immich-photo-manager?
Gestionar una gran biblioteca de fotos no debería requerir escribir scripts. Este servidor MCP convierte el lenguaje natural en gestión de la biblioteca, y está probado, no supuesto: 349 tests unitarios en cada push, y cada release se ejecuta en vivo contra Immich 2.7.5 y 3.1.0 reales con 132 comprobaciones que releen el servidor tras cada escritura.
| Manual / Scripts | immich-photo-manager | |
|---|---|---|
| 🔍 | Escribir llamadas API, parsear JSON | Consultas en lenguaje natural |
| 🌎 | Exportar GPS, clusterizar manualmente | GPS + CLIP + coincidencia temporal automática |
| 🗑 | Hashear archivos, comparar checksums | Hashing perceptual entre importaciones |
| 📊 | Consultar BD, construir informes | Evaluación integral con un comando |
| 📅 | Consultas SQL sobre timestamps | Detección automática de huecos |
| 🔄 | Rotar fotos de una en una | Rotación masiva de álbumes completos |
| 📄 | Buscar nombres de archivo y esperar suerte | Texto dentro de las fotos (OCR), personas, lugares |
| 🎬 | Una miniatura por vídeo | Frames de cualquier momento, hojas de contactos, PDF |
| 📝 | Repetir la revisión en cada sesión | El plugin recuerda cada veredicto y su porqué |
| 🔒 | Riesgo de errores de borrado | Seguridad primero, con aprobación |
Características
Búsqueda Inteligente
Busca tus fotos con lenguaje natural via embeddings CLIP. "Atardecer en la playa" encuentra exactamente lo que esperas.
Álbumes Geográficos
Organiza fotos automáticamente por ubicación usando datos GPS y CLIP. Álbumes curados con 20-50 fotos por lugar.
Limpieza de Biblioteca
Detecta capturas de pantalla, duplicados y fotos de baja calidad con análisis multi-señal. Revisa antes de cualquier acción.
Galerías HTML Interactivas
Di 'muéstrame fotos de Barcelona' y obtén una galería HTML autónoma: 3 temas (claro/sistema/oscuro), 4 modos de vista, presentación a pantalla completa, gestos táctiles, carga diferida. Se abre en cualquier navegador y funciona sin conexión.
94 Herramientas MCP
Toda la API de Immich que merece la pena: búsqueda, álbumes, personas, etiquetas, compartir, papelera, duplicados, memories, stacks, partners, comentarios, descargas, timeline y notas. Cada herramienta se prueba en vivo en Immich 2.7.5 y 3.1.0 antes de cada release.
Seguridad Primero
Nunca borra automáticamente. Siempre muestra hallazgos y pide confirmación. Tus fotos están seguras.
Rotación Masiva
Selecciona fotos mal orientadas, ponlas en un álbum y rota todo el lote de una vez. No destructivo, acumulativo, y se revierte con un solo comando.
Panel de Acciones Cowork
Selecciona fotos en cualquier galería, haz clic en una acción y el comando formateado se copia a tu portapapeles, listo para pegar en Cowork. 11 acciones con código de color, de Crear álbum a Borrar.
Frames de vídeo y fotolibros PDF
Claude ve un vídeo frame a frame, repasa un clip largo como hoja de contactos y construye un fotolibro PDF en tu máquina: una página completa por momento elegido, pies de foto, portada, índice y mapa. Fotos a calidad original.
Conocer la biblioteca antes de buscar
Una llamada dice qué sabe hacer el servidor (OCR, búsqueda inteligente, caras, versión). Después lugares, cámaras, un mapa mes a mes, un heatmap por día y una muestra aleatoria, sin descargar una sola foto.
Memories, stacks, partners
Recuerdos de "tal día como hoy", stacks que agrupan cuarenta tomas de la misma foto tras una portada sin borrar ninguna, biblioteca compartida entre cuentas, comentarios en álbumes compartidos y el álbum como zip.
Memoria de cada revisión
Los veredictos y sus razones se guardan en cada asset, junto a la foto que describen. Una sesión posterior se salta lo ya revisado en vez de pagar el análisis dos veces. Las etiquetas siguen siendo el estado visible en Immich; las notas llevan el porqué.
Arquitectura
Immich Photo Manager es un servidor Python que habla el Model Context Protocol, por stdio o HTTP, en las dos eras del protocolo (el handshake clásico y la especificación stateless 2026-07-28). Un cliente se conecta a él y traduce las peticiones a llamadas de la API REST de Immich, igual en 2.x que en 3.x.
94 herramientas en 21 categorías: Salud (4), Activos (9), Búsqueda (9), Álbumes (7), Compartir (5), Miniaturas (3), Imágenes (3), Vídeo (2), Exportar (2), Config (2), Personas (8), Papelera (4), Duplicados (2), Etiquetas (7), Memories (4), Timeline (3), Stacks (5), Partners (5), Actividades (3), Descarga (2) y Notas (5).
Inicio Rápido
Tres formas de entrar: uvx desde PyPI, el plugin de Claude Code con sus 13 skills, o la imagen Docker. Conectado en menos de dos minutos.
Instalar con uvx (recomendado)
Disponible en PyPI. Sin clonar repositorios, sin PYTHONPATH.
Instalar como plugin de Claude Code
La ruta con los 13 skills y los comandos slash. Después, /setup-immich-photo-manager pide la URL y la API key y las guarda.
Como contenedor Docker
Imagen oficial multi-arquitectura (amd64 y arm64). Sirve MCP por HTTP en el puerto 8626, las dos eras del protocolo, y /health para el healthcheck. Los PDFs y zips caen en /data.
Configuración manual
Luego añádelo a tu configuración de Claude (.mcp.json):
Skills Especializados
Trece flujos que combinan varias herramientas MCP en una sola petición, instalados con el plugin de Claude Code. Una frase dispara todo el proceso.
| Skill | Descripción |
|---|---|
/immich-status | Verificar salud del servidor, conteo de fotos/vídeos y uso de almacenamiento |
/create-album | Crear álbumes geográficos curados con 20-50 fotos por ubicación |
/cleanup | Detección multi-señal de capturas, duplicados y fotos de baja calidad, con stacks como opción suave y notas que recuerdan cada decisión |
/my-travels | Generar álbumes de viaje a partir de datos GPS de toda tu biblioteca |
/duplicate-report | Análisis profundo de duplicados entre fuentes usando hashing perceptual |
/library-health | Inventario de assets, calidad de metadatos, desglose de almacenamiento y recomendaciones |
/timeline-gaps | Identificar meses faltantes, periodos escasos y riesgos de cobertura |
/metadata-fixer | Reparar fechas rotas, GPS faltante, zonas horarias incorrectas via interpolación de vecinos |
/auto-album-curator | Encontrar nuevas fotos que coincidan con álbumes existentes via GPS, CLIP y patrones temporales |
/storage-optimizer | Identificar pares RAW+JPEG, vídeos sobredimensionados y archivos que acaparan espacio |
/people-report | Reconocimiento facial: quién aparece más, clusters sin nombre, primera y última aparición, fusiones que muestran los nombres antes de actuar |
/rotate-photos | Rotación masiva de álbumes o selecciones completas: no destructiva, acumulable, revertible con un clic |
/album-report | Convertir un álbum o una selección en PDF: portada, índice, mapa de lugares, una página por foto o por momento de vídeo elegido |
94 Herramientas MCP
Gestión completa de Immich en 21 categorías. Cada herramienta corresponde a un endpoint de la API de Immich que existe en 2.x y 3.x; las diferencias de versión se resuelven dentro del plugin.
| Categoría | Herramientas |
|---|---|
| Health (4) | ping, get_server_version, get_capabilities, get_statistics |
| Assets (9) | get_asset_info, reverse_geocode, update_asset_metadata, update_assets_metadata, rotate_assets, revert_asset_edits, get_map_markers, upload_asset, list_assets |
| Search (9) | search_metadata, search_smart (CLIP), search_explore, search_cities, search_places, search_suggestions, search_random, search_statistics, search_large_assets |
| Albums (7) | list_albums, get_album, create_album, update_album, delete_album, add_assets_to_album, remove_assets_from_album |
| Sharing (5) | list_shared_links, create_shared_link, get_shared_link, update_shared_link, delete_shared_link |
| Thumbnails (3) | get_asset_thumbnail, get_album_thumbnails, get_thumbnails_batch |
| Images (3) | get_asset_image, get_album_images, get_images_batch |
| Video (2) | get_video_frames, get_video_frames_json |
| Export (2) | get_export_preview, export_pdf |
| Config (2) | get_connection_info, update_credentials |
| People (8) | list_people, get_person, update_person, merge_people, search_people, get_person_thumbnail, get_asset_faces, reassign_face |
| Trash (4) | delete_assets, empty_trash, restore_trash, restore_assets |
| Duplicates (2) | get_duplicates, resolve_duplicates |
| Tags (7) | list_tags, get_tag, create_tag, update_tag, delete_tag, tag_assets, untag_assets |
| Memories (4) | list_memories, create_memory, update_memory, delete_memory |
| Timeline (3) | get_timeline_buckets, get_timeline_bucket, get_calendar_heatmap |
| Stacks (5) | create_stack, list_stacks, get_stack, update_stack, delete_stack |
| Partners (5) | list_users, list_partners, create_partner, update_partner, remove_partner |
| Activities (3) | list_activities, create_activity, delete_activity |
| Download (2) | get_download_info, download_archive |
| Notes (5) | review_assets, record_action, get_asset_notes, get_assets_notes, clear_asset_notes |
Instálalo como plugin de Claude Code y tienes los 13 skills más cinco comandos slash: /setup-immich-photo-manager, /immich-status, /create-album, /cleanup, /my-travels. Las credenciales se dan hablando y sobreviven a las actualizaciones del plugin. Claude Desktop, Cowork y otros clientes usan el servidor a secas por uvx o Docker.
Requisitos
Una instancia de Immich en marcha y un cliente MCP. Nada más.
| Requisito | Detalle |
|---|---|
| Immich | 2.x y 3.x, probado en vivo en 2.7.5 y 3.1.0 antes de cada release |
| Python | 3.10+ |
| Instalación | uvx immich-photo-manager (PyPI), claude plugin install o docker run ghcr.io/drolosoft/immich-photo-manager |
| macOS / Linux | Servidor Python; vídeo y PDF con wheels, sin ffmpeg del sistema |
| Clientes MCP | Claude Desktop, Claude Code, Cursor, Windsurf, LM Studio, cualquier cliente MCP, en las dos eras del protocolo (2025 y 2026-07-28) |
Construido Con
Un servidor Python con pocas dependencias. Los frames de vídeo y los PDF vienen como wheels, así que no hay nada que compilar ni ffmpeg que instalar.
- Python 3.10+ — Servidor async, ligero y portable
- mcp (SDK Python v2): Model Context Protocol por stdio o HTTP, las dos eras del protocolo
- API REST de Immich: gestión completa de la biblioteca en 2.x y 3.x
- Embeddings CLIP — Búsqueda de fotos con lenguaje natural via ML de Immich
- PyAV y fpdf2: frames cortados de cualquier vídeo, fotolibros PDF construidos en tu máquina
- Docker: imagen multi-arquitectura en GitHub Container Registry, publicada con cada release
Construyo las herramientas que me faltan, y las regalo.
Si alguna te ahorró tiempo, un café mantiene la siguiente en camino.
¿Listo para organizar tus fotos?
Immich Photo Manager es gratuito, de código abierto y listo para tu instancia de Immich: PyPI, plugin de Claude Code o Docker.