immich-photo-manager

Gestiona tu biblioteca de fotos autogestionada de Immich mediante conversación: búsqueda en lenguaje natural, curación de álbumes geográficos, detección de duplicados y galerías HTML interactivas.

GitHub

Prueba este MCPPatrocinado

Documentación

immich-photo-manager

Servidor MCP para gestión de fotos con Immich: tu biblioteca autoalojada, entendida.

Si tu biblioteca de Immich ha crecido más allá de lo que puedes gestionar a mano, immich-photo-manager da a cualquier asistente de IA acceso directo a tu instancia: busca, organiza, deduplica y cura álbumes mediante conversación natural. Funciona con Claude, Gemma o cualquier cliente compatible con MCP. Se ejecuta localmente y solo habla con tu Immich; tus originales permanecen en tu servidor (consulta qué sale de tu red).

Probado, no asumido. Cada push ejecuta 355 pruebas unitarias en CI. Cada versión también se ejecuta en vivo contra Immich real 2.7.5 y 3.1.0 (Docker, las 94 herramientas sobre la era heredada del protocolo MCP, relectura del estado después de cada escritura) antes de etiquetarse; ambas eras del protocolo (el handshake heredado y el sin estado de 2026-07-28) se fijan en cada push mediante pruebas de cable sin SDK (tests/test_raw_wire_eras.py). El kit está en tests/live/, reproducible por cualquiera. Las demos en doc/demos/ son transcripciones de sesiones reales, Demo 11 es este flujo exacto paso a paso, y Demo 12 ejecuta los fotogramas de video y el fotolibro PDF en un clip real. Las demos 13 a 18 cubren todo lo añadido en 2.x (descubrimiento de biblioteca, OCR y búsqueda de personas, recuerdos y pilas, socios y descargas, notas de activos, la imagen Docker) de sesiones reales. Detalles: Cómo se prueba.

immich-photo-manager demo

Qué Hace

Di "crea álbumes para todos mis viajes" y observa cómo funciona:

Geographic album creation

Coordenadas GPS, búsqueda visual CLIP y coincidencia temporal, combinadas en una sola solicitud para crear docenas de álbumes curados. Sin scripts, sin ordenación manual.

Inicio Rápido

Requisitos previos

Una instancia de Immich en ejecución (autoalojada, v1.90+)
Una clave de API de Immich (cómo crearla)
Python 3.10+ con pip (descargar)

Instalación (plugin de Claude Code)

git clone https://github.com/drolosoft/immich-photo-manager.git
cd immich-photo-manager
pip3 install -r src/requirements.txt      # the plugin runs on your system python3

claude plugin marketplace add ./
claude plugin install immich-photo-manager

Abre Claude Code (reinícialo si ya estaba abierto) y conéctalo a tu Immich. Guiado:

/setup-immich-photo-manager

Pide tu URL del servidor y clave de API, las verifica contra el servidor, las guarda y muestra los números de tu biblioteca:

/setup-immich-photo-manager: connected, Immich version and library size

O salta la guía y dilo en una línea (lo mismo por debajo):

Update my Immich credentials to http://immich.local:2283 with API key <your API key>

De cualquier manera, las credenciales se guardan para cada sesión a partir de entonces; repite para cambiar servidor o clave. Confirma en cualquier momento con:

What Immich version am I connected to?

Eso es toda la instalación. ¿Usas Claude Desktop, Cowork u otro cliente MCP en lugar de Claude Code? Ese es el servidor MCP simple sin las habilidades: consulta Cómo empezar, ruta B.

Actualizar el plugin

Una línea, sin reinstalar:

cd immich-photo-manager && git pull      # the clone you installed from
claude plugin marketplace update drolosoft-marketplace
claude plugin update immich-photo-manager@drolosoft-marketplace

Luego reinicia Claude Code. drolosoft-marketplace es el nombre que el marketplace obtiene cuando lo añades desde el clon (claude plugin marketplace list lo muestra). Tus credenciales guardadas se conservan.

Después de extraer una nueva versión, ejecuta pip3 install -r src/requirements.txt de nuevo: 1.7.1 añadió las bibliotecas de video (av) y PDF (fpdf2) a las dependencias del plugin. En la ruta uvx, uvx --refresh immich-photo-manager --help una vez, luego reinicia el cliente.

Qué sale de tu red

El proceso del plugin se ejecuta en tu máquina y solo habla con tu Immich. Pero todo lo que el asistente lee a través de él va al modelo que uses: nombres de archivo, fechas, EXIF, listas de álbumes y, cuando le pides que mire fotos, miniaturas (250px por defecto, vistas previas de 1440px bajo petición). Los originales nunca se obtienen. Con Claude, eso significa que esas miniaturas salen de tu red; con un modelo local sobre MCP (LM Studio, Ollama) nada sale. Nada se envía a menos que lo pidas: listar álbumes o corregir fechas mueve solo texto, "dime qué hay en estas fotos" mueve imágenes.

Un informe PDF sigue la misma regla: export_pdf escribe el archivo en el disco de la máquina que ejecuta el servidor, y no se envía a ningún sitio a menos que pases return_base64=true. El archivo va donde dice output_path (por defecto tu Escritorio); los archivos existentes nunca se sobrescriben. Los fotogramas que solo van al PDF nunca salen de tu máquina y no cuestan tokens; solo los fotogramas que pides al modelo que mire lo hacen. Cuando los activos llevan GPS, la página de Lugares dibuja un mapa con teselas de tile.openstreetmap.org, la única llamada de terceros que hace este plugin; pasa map=false para omitirla y mantener todo dentro de tu red.

Conectar, comprobar, cambiar: todo hablando

Nunca editas archivos de configuración después de la instalación. La conexión se gestiona en conversación:

Tú dices	Qué ocurre
"¿A qué versión de Immich estoy conectado?"	Informa de la versión del servidor y la URL a la que habla
"Actualiza mis credenciales de Immich a `https://photos.example.com` con clave de API `...`"	Valida la clave contra ese servidor, cambia en caliente la conexión activa, la persiste, sin reinicio
"Muestra mi conexión de Immich"	URL + clave de API enmascarada

Una conexión a la vez: para trabajar con un segundo Immich (una instancia de prueba, el servidor de un amigo), di la frase de actualizar de nuevo; dilo una vez más para volver. ¿URL o clave incorrectas? Te lo dice y mantiene la conexión anterior.

Prueba el recorrido completo: Demo 11, Recorrido de Álbumes. Lee un álbum elemento a elemento, encuentra quién se repite, crea un sub-álbum, etiqueta y describe cada foto.

Funciona en Claude Code

El mismo plugin se ejecuta en Claude Code: busca en tu biblioteca, cura álbumes y genera galerías directamente desde la terminal.

Split screen: Claude Code terminal generating a photo gallery on the left, browser showing the resulting gallery with album cards on the right

Transcripción completa de la conversación: Demo de Claude Code

Funciona con Cualquier Cliente MCP

immich-photo-manager es un servidor MCP: funciona con cualquier asistente de IA que hable el Protocolo de Contexto de Modelo, no solo Claude.

Usa el punto de entrada del paquete directamente con uvx:

{
  "mcpServers": {
    "immich": {
      "command": "uvx",
      "args": ["immich-photo-manager"],
      "env": {
        "IMMICH_BASE_URL": "https://your-immich-server.com",
        "IMMICH_API_KEY": "your-api-key"
      }
    }
  }
}

immich-photo-manager usa por defecto el transporte stdio de MCP. Establece MCP_TRANSPORT=http cuando quieras ejecutar el servidor como un servicio HTTP Streamable.

🐳 Ejecutar como contenedor Docker

El servidor también se distribuye como imagen multi-arquitectura (amd64 + arm64) en GitHub Container Registry, sirviendo MCP sobre HTTP en el puerto 8626, ambas eras del protocolo, las mismas 94 herramientas:

docker run -d -p 8626:8626 \
  -e IMMICH_BASE_URL=https://your-immich-server.com \
  -e IMMICH_API_KEY=your-api-key \
  -v ./exports:/data \
  ghcr.io/drolosoft/immich-photo-manager

Apunta cualquier cliente HTTP Streamable a http://localhost:8626/mcp. El liveness está en /health (sin necesidad de credenciales, conectado como HEALTHCHECK de la imagen). Las herramientas que escriben archivos (export_pdf, download_archive) los dejan en /data, así que monta un volumen allí. Alcanzar el contenedor bajo un nombre distinto de localhost (un proxy inverso, otro contenedor) necesita ese nombre en -e MCP_ALLOWED_HOSTS=.... La protección contra rebinding de DNS permanece activada.

Las variables de entorno son opcionales: un contenedor iniciado sin ellas sigue sirviendo, cada herramienta responde "No hay credenciales de Immich configuradas" con la solución, y una llamada a update_credentials (base_url + api_key) lo conecta, persistido bajo /data, así que con el volumen montado sobrevive a reinicios y recreaciones.

Lo mismo como servicio Compose, junto a un stack de Immich o por su cuenta:

services:
  immich-mcp:
    image: ghcr.io/drolosoft/immich-photo-manager
    ports:
      - "8626:8626"
    environment:
      IMMICH_BASE_URL: https://your-immich-server.com
      IMMICH_API_KEY: your-api-key
      # MCP_ALLOWED_HOSTS: photos-mcp.example.com   # only behind a proxy / other hostname
    volumes:
      - ./exports:/data
    restart: unless-stopped

Claude Desktop en macOS: la aplicación no ve el PATH de tu shell, así que escribe la ruta completa a uvx en "command" (ejecuta which uvx en una terminal; normalmente /Users/<you>/.local/bin/uvx o /opt/homebrew/bin/uvx). Ejecuta uvx immich-photo-manager --help una vez en una terminal para que la primera descarga se complete, luego sal de Claude Desktop con Cmd+Q y vuelve a abrirlo. Si aún no aparece, la razón está en ~/Library/Logs/Claude/mcp-server-immich.log.

============================================================
IMMICH-PHOTO-MANAGER × GEMMA 4 (LM STUDIO)
============================================================

Immich: https://your-immich-server.com
Model:  gemma4-26b-it (local, LM Studio)
Query:  "Show me my Lanzarote albums"

1. Getting MCP tool schemas...
   94 MCP tools available

2. Asking Gemma 4...
   Gemma 4 chose: list_albums({})

3. Executing 'list_albums' against Immich...
   Found 124 total albums, 14 Lanzarote albums:
     - Lanzarote Amarillo (26 photos)
     - Lanzarote Rojo (201 photos)
     - Lanzarote Azul (187 photos)
     - Lanzarote Marrón (208 photos)
     - Lanzarote Negro (193 photos)
     - Lanzarote Verde (201 photos)
     - Lanzarote Gasolina (174 photos)
     ...

4. Gemma 4 interpreting results...
   "I found 14 Lanzarote albums, 7 color-themed with
    1,190 photos and 7 location-specific albums."

RESULT: Zero cloud dependency, fully self-hosted stack.

Cliente	Estado
Claude Code	Probado
Claude Desktop	Probado
LM Studio (Gemma 4)	Probado
Cursor, Windsurf, VS Code, Cline, Zed	Compatible (MCP stdio)

Transcripción completa: Demo de Gemma 4 · Script de prueba: test-lmstudio-mcp.py

Destacados

Búsqueda impulsada por IA: búsqueda de fotos en lenguaje natural mediante CLIP ("atardecer en la playa", "pastel de cumpleaños")
Álbumes geográficos: crea álbumes organizados por lugar, combinando GPS + CLIP + coincidencia temporal
Reparación de metadatos: corrige marcas de tiempo de mediodía/medianoche, infiere GPS faltante de fotos vecinas, corrige desfases de zona horaria
Limpieza de biblioteca: detecta capturas de pantalla, duplicados e imágenes de baja calidad con análisis de múltiples señales; los casi duplicados y ráfagas se pueden apilar detrás de la mejor toma en lugar de eliminarse, lo cual es reversible
Detección de duplicados: análisis entre fuentes usando hash perceptual (encuentra copias recodificadas entre Apple Photos, Google Photos y otras importaciones)
Rotación masiva: rota álbumes enteros o selecciones de una vez (90°/180°/270°); no destructiva, se acumula entre llamadas, revierte con un clic
Informes PDF: álbum o selección a un PDF con metadatos, fotogramas de video y pies de foto de Claude, construido en tu máquina; el diseño de fotolibro da a cada momento de video elegido una página completa con su propio pie de foto, y las páginas de portada/índice/lugares son opcionales
Fotogramas de video: corta fotogramas espaciados uniformemente de cualquier clip, o un segmento (start/end) hasta un fotograma por segundo (interval), para que Claude pueda describir lo que ocurre en él; Immich mismo guarda un póster por video
Gestión de personas y rostros: lista, busca, fusiona y organiza personas reconocidas; reasigna rostros mal identificados; ve miniaturas de rostros
Papelera y ciclo de vida de activos: elimina activos de forma segura a la papelera, elimina permanentemente, restaura desde la papelera; gestión completa del ciclo de vida de activos
Salud de la biblioteca: un comando para inventario de activos, calidad de metadatos, desglose de almacenamiento y recomendaciones
Etiquetas y organización: crea, aplica y gestiona etiquetas en toda tu biblioteca; etiqueta y desetiqueta activos en masa
Consciente del servidor: una llamada informa de la versión de Immich, qué funciones están activadas (OCR, búsqueda inteligente, rostros, mapa) y el comportamiento conocido de esa versión mayor, para que no se ofrezca nada que el servidor no pueda hacer
Texto dentro de fotos: OCR encuentra el texto en una foto (un billete, una señal de calle), y las llamadas de explorar, ciudad y sugerencias devuelven las ortografías exactas que los filtros esperan en lugar de suposiciones
Fechas en una llamada: cubos mes a mes, un mapa de calor de calendario que muestra huecos y días ocupados, y los recuerdos "en este día" de Immich
Compartir, en ambas direcciones: bibliotecas de socios (compartir familiar de Immich) y los comentarios y me gusta que la gente deja en un álbum compartido
Originales fuera: un álbum o una selección como un zip en tu máquina, con el tamaño informado antes de que comience la descarga
Notas entre sesiones: veredictos y acciones almacenados en cada activo, para que la próxima limpieza omita lo que una pasada anterior ya revisó
Se ejecuta en Docker: imagen multi-arquitectura que sirve MCP sobre HTTP en el puerto 8626, ambas eras del protocolo, las mismas 94 herramientas
Galerías interactivas: páginas HTML autocontenidas con miniaturas incrustadas, 3 temas, 4 modos de vista y un Panel de Acciones de Cowork para operaciones por lotes

Interactive gallery with Cowork Actions

Selecciona fotos en la galería, haz clic en una acción y pega el comando en Claude. Consulta Referencia de Habilidades para las 13 habilidades.

Herramientas

Las 94 herramientas por área. Parámetros, formas de retorno y ejemplos para cada una están en la Referencia de Herramientas MCP.

Búsqueda: search_smart, search_metadata, search_explore, search_cities, search_places, search_suggestions, search_random, search_statistics, search_large_assets, list_assets
Álbumes: list_albums, get_album, create_album, update_album, delete_album, add_assets_to_album, remove_assets_from_album
Recursos y metadatos: get_asset_info, update_asset_metadata, update_assets_metadata, rotate_assets, revert_asset_edits, get_map_markers, reverse_geocode, upload_asset
Imágenes y miniaturas: get_asset_image, get_album_images, get_images_batch, get_asset_thumbnail, get_album_thumbnails, get_thumbnails_batch
Vídeo y PDF: get_video_frames, get_video_frames_json, get_export_preview, export_pdf
Personas y rostros: list_people, get_person, update_person, merge_people, search_people, get_person_thumbnail, get_asset_faces, reassign_face
Duplicados y pilas: get_duplicates, resolve_duplicates, create_stack, list_stacks, get_stack, update_stack, delete_stack
Etiquetas: list_tags, get_tag, create_tag, update_tag, delete_tag, tag_assets, untag_assets
Fechas: get_timeline_buckets, get_timeline_bucket, get_calendar_heatmap, list_memories, create_memory, update_memory, delete_memory
Compartir: list_shared_links, create_shared_link, get_shared_link, update_shared_link, delete_shared_link, list_users, list_partners, create_partner, update_partner, remove_partner, list_activities, create_activity, delete_activity
Descarga: get_download_info, download_archive
Papelera: delete_assets, empty_trash, restore_trash, restore_assets
Notas de recursos: review_assets, record_action, get_asset_notes, get_assets_notes, clear_asset_notes
Servidor y conexión: ping, get_server_version, get_capabilities, get_statistics, get_connection_info, update_credentials

¿Por qué immich-photo-manager?

Immich es excelente para almacenar y ver tus fotos. Pero gestionar una biblioteca grande (deduplicación, reparación de metadatos, curación de álbumes, análisis de almacenamiento) aún requiere esfuerzo manual o scripts personalizados.

	Manual / scripts	immich-photo-manager
🔍	Escribir llamadas API, analizar JSON	Lenguaje natural: "encuentra mis fotos de atardecer en Italia"
🗺️	Exportar GPS, agrupar manualmente	Álbumes geográficos: coincidencia automática por GPS + CLIP + temporal
🧹	Hash de archivos, comparar checksums	Hash perceptual: encuentra duplicados recodificados entre fuentes de importación
🔧	Editar EXIF un archivo a la vez	Reparación de metadatos: corregir marcas de tiempo por lotes, inferir GPS, corregir zonas horarias
📊	Consultar base de datos, crear informes	Salud de la biblioteca: un comando para calidad de metadatos, almacenamiento, recomendaciones
🔄	Rotar una foto a la vez	Rotación masiva: rotar álbumes enteros de una vez, no destructiva
🏷️	Sin gestión de etiquetas en la interfaz	Etiquetas: crear, aplicar/eliminar en masa entre recursos
📅	Desplazarse por la línea de tiempo buscando huecos	Mapa de línea de tiempo: agrupación mensual y mapa de calor de calendario en una llamada, huecos incluidos
🔤	Buscar en nombres de archivo y esperar	Búsqueda OCR: encontrar una foto por el texto que contiene
📦	SSH y comprimir los archivos manualmente	Archivo de descarga: originales del álbum en un zip, tamaño conocido de antemano
🧠	Redecidir las mismas fotos en cada sesión	Notas de recursos: el veredicto permanece en el recurso, la siguiente pasada lo omite
🛡️	Revisión manual de cada acción	Seguridad primero: muestra hallazgos, pregunta antes de actuar

Cómo se prueba

Suite de pruebas unitarias, en cada push: 355 casos de pytest en Python 3.10 y 3.13 (HTTP simulado), además de ruff. Las versiones solo se etiquetan cuando esta puerta está en verde.
En vivo, cada herramienta, dos versiones de Immich: tests/live/ inicia Immich real 2.7.5 y 3.1.0 en Docker, los llena con una biblioteca pequeña y ejecuta las 94 herramientas a través del protocolo MCP, releyendo el estado después de cada escritura. Se ejecuta antes de cada versión; última ejecución completa 2026-09-03, 132/132 comprobaciones en ambas.
En uso: descargas de PyPI, PRs fusionados de cuatro colaboradores externos, y las demostraciones en doc/demos/ son transcripciones de sesiones reales.

Construido con Claude

Este es un plugin de Claude, y Claude es un colaborador en el código: el diseño, las decisiones de compatibilidad de API y qué probar son del autor; una buena parte de la implementación y el arnés de pruebas se escribieron con Claude Code. Cada cambio pasa por la misma puerta de cualquier manera: pruebas en CI, y para cualquier cosa que toque la API de Immich, la ejecución en vivo anterior.

Documentación

Documento	Descripción
Primeros pasos	Instalación, configuración manual de MCP, opciones de despliegue y solución de problemas
Configuración del entorno	Configuración detallada: git, Python, venv, lanzamiento HTTP/stdio, Open WebUI y problemas comunes
Referencia de habilidades	Las 13 habilidades: flujos de trabajo, disparadores, parámetros, formatos de salida
Referencia de herramientas MCP	Las 94 herramientas MCP: parámetros, tipos de retorno, ejemplos
Arquitectura	Cómo las miniaturas incrustadas en base64 resuelven la restricción del sandbox de Cowork
MCP 2026-07-28	Soporte de doble era: handshake heredado y la revisión sin estado desde un servidor, y cómo se verifica
Guía de configuración CORS	Opcional, habilita la carga directa de miniaturas por URL para galerías vistas en navegador

🦙 Puntuación Glama

Contribuciones

Las contribuciones son bienvenidas: correcciones de errores, nuevas habilidades, ideas de funciones. Abre un issue o envía un PR.

Si immich-photo-manager ayuda a gestionar tu biblioteca, considera darle una estrella en GitHub. Ayuda a que otros descubran el proyecto.

Soporte

Si immich-photo-manager te ahorró tiempo o hizo que tu biblioteca de fotos sea más fácil de gestionar, considera invitarme a un café. ¡Mantiene la próxima versión en camino!

Licencia

Licencia MIT: libre de usar, modificar y distribuir.

Forjado por Drolosoft · Herramientas que deseamos que existieran