immich-photo-manager

Gerencie sua biblioteca de fotos auto-hospedada Immich por meio de conversas — pesquisa em linguagem natural, curadoria de álbuns geográficos, detecção de duplicatas e galerias HTML interativas

GitHub

Experimente este MCPPatrocinado

Documentação

immich-photo-manager

Servidor MCP para gerenciamento inteligente de fotos com Immich: sua biblioteca auto-hospedada, compreendida.

Se sua biblioteca Immich cresceu além do que você consegue gerenciar manualmente, o immich-photo-manager dá a qualquer assistente de IA acesso direto à sua instância: pesquise, organize, deduplique e curadoria de álbuns por meio de conversa natural. Funciona com Claude, Gemma ou qualquer cliente compatível com MCP. Roda localmente e fala apenas com o seu Immich; seus originais permanecem no seu servidor (veja o que sai da sua rede).

Testado, não presumido. Cada push executa 355 testes unitários no CI. Cada release também é executado ao vivo contra Immich real 2.7.5 e 3.1.0 (Docker, todas as 94 ferramentas sobre a era legada do protocolo MCP, re-leitura do estado após cada escrita) antes de ser marcado; ambas as eras do protocolo (o handshake legado e o stateless 2026-07-28) são fixadas em cada push por testes de wire sem SDK (tests/test_raw_wire_eras.py). O kit está em tests/live/, reproduzível por qualquer pessoa. As demos em doc/demos/ são transcrições de sessões reais, Demo 11 é este fluxo exato prompt por prompt, e Demo 12 executa os frames de vídeo e o fotolivro PDF em um clipe real. As demos 13 a 18 cobrem tudo adicionado na 2.x (descoberta de biblioteca, OCR e busca de pessoas, memórias e stacks, parceiros e downloads, notas de ativos, imagem Docker) de sessões reais. Detalhes: Como é testado.

immich-photo-manager demo

O Que Ele Faz

Diga "crie álbuns para todas as minhas viagens" e veja funcionar:

Geographic album creation

Coordenadas GPS, busca visual CLIP e correspondência temporal, combinadas em uma única solicitação para criar dezenas de álbuns curados. Sem scripts, sem organização manual.

Início Rápido

Pré-requisitos

Uma instância Immich em execução (auto-hospedada, v1.90+)
Uma chave de API do Immich (como criar uma)
Python 3.10+ com pip (download)

Instalação (plugin 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

Abra o Claude Code (reinicie se já estiver aberto) e conecte-o ao seu Immich. Guiado:

/setup-immich-photo-manager

Ele pergunta sua URL do servidor e chave de API, verifica-as contra o servidor, salva-as e mostra os números da sua biblioteca:

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

Ou pule o guia e diga em uma linha (mesma coisa por baixo):

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

De qualquer forma, as credenciais são salvas para todas as sessões a partir de então; repita para mudar servidor ou chave. Confirme a qualquer momento com:

What Immich version am I connected to?

Essa é a instalação completa. Claude Desktop, Cowork ou outro cliente MCP em vez do Claude Code? Esse é o servidor MCP puro sem as skills: veja Começando, rota B.

Atualizar o plugin

Uma linha, sem reinstalação:

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

Depois reinicie o Claude Code. drolosoft-marketplace é o nome que o marketplace recebe quando você o adiciona do clone (claude plugin marketplace list mostra isso). Suas credenciais salvas são mantidas.

Após puxar uma nova versão, execute pip3 install -r src/requirements.txt novamente: 1.7.1 adicionou as bibliotecas de vídeo (av) e PDF (fpdf2) às dependências do plugin. Na rota uvx, uvx --refresh immich-photo-manager --help uma vez, depois reinicie o cliente.

O que sai da sua rede

O processo do plugin roda na sua máquina e só fala com o seu Immich. Mas tudo o que o assistente lê através dele vai para o modelo que você usa: nomes de arquivo, datas, EXIF, listas de álbuns e, quando você pede para olhar fotos, thumbnails (250px por padrão, previews de 1440px sob solicitação). Os originais nunca são buscados. Com Claude, isso significa que esses thumbnails saem da sua rede; com um modelo local via MCP (LM Studio, Ollama), nada sai. Nada é enviado a menos que você peça: listar álbuns ou corrigir datas move apenas texto, "me diga o que há nessas fotos" move imagens.

Um relatório PDF segue a mesma regra: export_pdf escreve o arquivo no disco da máquina que executa o servidor, e ele não é enviado a lugar nenhum a menos que você passe return_base64=true. O arquivo vai para onde output_path indica (padrão: sua Área de Trabalho); arquivos existentes nunca são sobrescritos. Frames que só vão para o PDF nunca saem da sua máquina e não custam tokens; apenas os frames que você pede ao modelo para olhar saem. Quando os ativos têm GPS, a página de Lugares desenha um mapa com tiles de tile.openstreetmap.org, a única chamada de terceiros que este plugin faz; passe map=false para pular isso e manter tudo dentro da sua rede.

Conectar, verificar, alternar: tudo conversando

Você nunca edita arquivos de configuração após a configuração. A conexão é gerenciada em conversa:

Você diz	O que acontece
"Qual versão do Immich estou conectado?"	Relata a versão do servidor e a URL com a qual está falando
"Atualize minhas credenciais do Immich para `https://photos.example.com` com chave de API `...`"	Valida a chave contra esse servidor, troca a conexão ativa em tempo real, persiste, sem reiniciar
"Mostre minha conexão Immich"	URL + chave de API mascarada

Uma conexão por vez: para trabalhar com um segundo Immich (uma instância de teste, o servidor de um amigo), diga a frase de atualização novamente; diga mais uma vez para voltar. URL ou chave errada? Ele avisa e mantém a conexão anterior.

Experimente o passo a passo completo: Demo 11, Passo a Passo de Álbum. Leia um álbum item por item, descubra quem se repete, crie um sub-álbum, marque e descreva cada foto.

Funciona no Claude Code

O mesmo plugin roda no Claude Code: pesquise sua biblioteca, curadoria de álbuns e gere galerias direto do terminal.

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

Transcrição completa da conversa: Demo Claude Code

Funciona com Qualquer Cliente MCP

immich-photo-manager é um servidor MCP: funciona com qualquer assistente de IA que fale o Model Context Protocol, não apenas Claude.

Use o ponto de entrada do pacote diretamente com 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 como padrão o transporte stdio do MCP. Defina MCP_TRANSPORT=http quando quiser executar o servidor como um serviço HTTP Streamable.

🐳 Execute como contêiner Docker

O servidor também é distribuído como imagem multi-arquitetura (amd64 + arm64) no GitHub Container Registry, servindo MCP via HTTP na porta 8626, ambas as eras do protocolo, mesmas 94 ferramentas:

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

Aponte qualquer cliente Streamable HTTP para http://localhost:8626/mcp. A liveness está em /health (sem necessidade de credenciais, conectada como HEALTHCHECK da imagem). As ferramentas que escrevem arquivos (export_pdf, download_archive) os colocam em /data, então monte um volume lá. Acessar o contêiner sob um nome diferente de localhost (um proxy reverso, outro contêiner) precisa desse nome em -e MCP_ALLOWED_HOSTS=.... A proteção contra DNS-rebinding permanece ativa.

As variáveis de ambiente são opcionais: um contêiner iniciado sem elas ainda serve, toda ferramenta responde "Nenhuma credencial Immich configurada" com a correção, e uma chamada update_credentials (base_url + api_key) o conecta, persistida em /data, então com o volume montado ele sobrevive a reinicializações e recriações.

O mesmo como serviço Compose, ao lado de uma stack Immich ou sozinho:

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 no macOS: o aplicativo não vê o PATH do seu shell, então escreva o caminho completo para uvx em "command" (execute which uvx em um terminal; tipicamente /Users/<you>/.local/bin/uvx ou /opt/homebrew/bin/uvx). Execute uvx immich-photo-manager --help uma vez em um terminal para que o primeiro download seja concluído, depois saia do Claude Desktop com Cmd+Q e reabra. Se ainda não aparecer, o motivo está em ~/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	Status
Claude Code	Testado
Claude Desktop	Testado
LM Studio (Gemma 4)	Testado
Cursor, Windsurf, VS Code, Cline, Zed	Compatível (MCP stdio)

Transcrição completa: Demo Gemma 4 · Script de teste: test-lmstudio-mcp.py

Destaques

Busca com IA: busca de fotos por linguagem natural via CLIP ("pôr do sol na praia", "bolo de aniversário")
Álbuns geográficos: crie álbuns organizados por lugar, combinando GPS + CLIP + correspondência temporal
Reparo de metadados: corrija timestamps de meio-dia/meia-noite, infira GPS ausente de fotos vizinhas, corrija offsets de fuso horário
Limpeza de biblioteca: detecte capturas de tela, duplicatas e imagens de baixa qualidade com análise multi-sinal; quase-duplicatas e bursts podem ser empilhados atrás da melhor foto em vez de excluídos, o que é reversível
Detecção de duplicatas: análise entre fontes usando hash perceptual (encontra cópias re-encodadas entre Apple Photos, Google Photos e outras importações)
Rotação em lote: gire álbuns inteiros ou seleções de uma vez (90°/180°/270°); não destrutivo, acumula entre chamadas, reversão com um clique
Relatórios PDF: álbum ou seleção para PDF com metadados, frames de vídeo e legendas do Claude, construído na sua máquina; o layout de fotolivro dá a cada momento de vídeo escolhido uma página inteira com sua própria legenda, e as páginas de capa/índice/lugares são opcionais
Frames de vídeo: corte frames igualmente espaçados de qualquer clipe, ou um segmento (start/end) até um frame por segundo (interval), para que o Claude possa descrever o que acontece nele; o próprio Immich mantém um poster por vídeo
Gerenciamento de pessoas e rostos: liste, pesquise, mescle e organize pessoas reconhecidas; reatribua rostos identificados incorretamente; veja thumbnails de rostos
Lixeira e ciclo de vida de ativos: exclua ativos com segurança para a lixeira, remova permanentemente, restaure da lixeira; gerenciamento completo do ciclo de vida de ativos
Saúde da biblioteca: um comando para inventário de ativos, qualidade de metadados, distribuição de armazenamento e recomendações
Tags e organização: crie, aplique e gerencie tags em toda a biblioteca; marque e desmarque ativos em lote
Ciente do servidor: uma chamada relata a versão do Immich, quais recursos estão ativados (OCR, busca inteligente, rostos, mapa) e o comportamento conhecido dessa versão principal, para que nada seja oferecido que o servidor não possa fazer
Texto dentro de fotos: OCR encontra o texto em uma foto (um ingresso, uma placa de rua), e as chamadas de explorar, cidade e sugestões retornam as grafias exatas que os filtros esperam em vez de suposições
Datas em uma chamada: buckets mês a mês, um heatmap de calendário que mostra lacunas e dias movimentados, e as memórias "neste dia" do Immich
Compartilhamento, nas duas direções: bibliotecas de parceiros (compartilhamento familiar do Immich) e os comentários e curtidas que as pessoas deixam em um álbum compartilhado
Originais para fora: um álbum ou seleção como um zip na sua máquina, com o tamanho relatado antes do download começar
Notas entre sessões: veredictos e ações armazenados em cada ativo, para que a próxima limpeza pule o que uma passagem anterior já revisou
Roda em Docker: imagem multi-arquitetura servindo MCP via HTTP na porta 8626, ambas as eras do protocolo, mesmas 94 ferramentas
Galerias interativas: páginas HTML autônomas com thumbnails incorporados, 3 temas, 4 modos de visualização e um Painel de Ações Cowork para operações em lote

Interactive gallery with Cowork Actions

Selecione fotos na galeria, clique em uma ação e cole o comando no Claude. Veja Referência de Skills para todas as 13 skills.

Ferramentas

As 94 ferramentas por área. Parâmetros, formatos de retorno e exemplos para cada uma estão na Referência de Ferramentas MCP.

Busca: search_smart, search_metadata, search_explore, search_cities, search_places, search_suggestions, search_random, search_statistics, search_large_assets, list_assets
Álbuns: list_albums, get_album, create_album, update_album, delete_album, add_assets_to_album, remove_assets_from_album
Ativos e metadados: get_asset_info, update_asset_metadata, update_assets_metadata, rotate_assets, revert_asset_edits, get_map_markers, reverse_geocode, upload_asset
Imagens e miniaturas: get_asset_image, get_album_images, get_images_batch, get_asset_thumbnail, get_album_thumbnails, get_thumbnails_batch
Vídeo e PDF: get_video_frames, get_video_frames_json, get_export_preview, export_pdf
Pessoas e rostos: list_people, get_person, update_person, merge_people, search_people, get_person_thumbnail, get_asset_faces, reassign_face
Duplicatas e pilhas: 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
Datas: get_timeline_buckets, get_timeline_bucket, get_calendar_heatmap, list_memories, create_memory, update_memory, delete_memory
Compartilhamento: 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
Download: get_download_info, download_archive
Lixeira: delete_assets, empty_trash, restore_trash, restore_assets
Notas de ativos: review_assets, record_action, get_asset_notes, get_assets_notes, clear_asset_notes
Servidor e conexão: ping, get_server_version, get_capabilities, get_statistics, get_connection_info, update_credentials

Por que immich-photo-manager?

O Immich é excelente para armazenar e visualizar suas fotos. Mas gerenciar uma biblioteca grande (deduplicação, reparo de metadados, curadoria de álbuns, análise de armazenamento) ainda exige esforço manual ou scripts personalizados.

	Manual / scripts	immich-photo-manager
🔍	Escrever chamadas de API, analisar JSON	Linguagem natural: "encontre minhas fotos de pôr do sol na Itália"
🗺️	Exportar GPS, agrupar manualmente	Álbuns geográficos: correspondência automática por GPS + CLIP + temporal
🧹	Hash de arquivos, comparar checksums	Hash perceptual: encontra duplicatas re-codificadas entre fontes de importação
🔧	Editar EXIF um arquivo por vez	Reparo de metadados: correção em lote de timestamps, inferência de GPS, correção de fusos horários
📊	Consultar banco de dados, criar relatórios	Saúde da biblioteca: um comando para qualidade de metadados, armazenamento, recomendações
🔄	Rotacionar uma foto por vez	Rotação em lote: rotacione álbuns inteiros de uma vez, sem destruição
🏷️	Sem gerenciamento de etiquetas na interface	Etiquetas: criar, aplicar/remover em lote entre ativos
📅	Rolar a linha do tempo procurando lacunas	Mapa da linha do tempo: buckets mensais e um heatmap de calendário em uma chamada, lacunas incluídas
🔤	Buscar em nomes de arquivo e torcer	Busca OCR: encontre uma foto pelo texto dentro dela
📦	Acessar via SSH e compactar os arquivos manualmente	Arquivo de download: originais do álbum em um único zip, tamanho conhecido antecipadamente
🧠	Re-decidir as mesmas fotos a cada sessão	Notas de ativos: o veredito permanece no ativo, a próxima passagem o ignora
🛡️	Revisão manual de cada ação	Segurança em primeiro lugar: mostra descobertas, pergunta antes de agir

Como é testado

Suíte de testes unitários, a cada push: 355 casos pytest em Python 3.10 e 3.13 (HTTP simulado), além de ruff. Releases são marcadas apenas quando essa etapa está verde.
Ao vivo, cada ferramenta, duas versões do Immich: tests/live/ inicia Immich real 2.7.5 e 3.1.0 em Docker, preenche-os com uma pequena biblioteca e aciona todas as 94 ferramentas pelo protocolo MCP, relendo o estado após cada escrita. Executado antes de cada release; última execução completa em 2026-09-03, 132/132 verificações em ambos.
Em uso: downloads no PyPI, PRs mesclados de quatro colaboradores externos, e as demonstrações em doc/demos/ são transcrições de sessões reais.

Construído com Claude

Este é um plugin do Claude, e o Claude é um colaborador no código: o design, as decisões de compatibilidade de API e o que testar são do autor; boa parte da implementação e do harness de testes foi escrita com Claude Code. Cada mudança passa pelo mesmo portão de qualquer forma: testes no CI e, para qualquer coisa que toque na API do Immich, a execução ao vivo acima.

Documentação

Documento	Descrição
Começando	Instalação, configuração manual do MCP, opções de implantação e solução de problemas
Configuração do Ambiente	Configuração detalhada: git, Python, venv, inicialização HTTP/stdio, Open WebUI e problemas comuns
Referência de Habilidades	Todas as 13 habilidades: fluxos de trabalho, gatilhos, parâmetros, formatos de saída
Referência de Ferramentas MCP	Todas as 94 ferramentas MCP: parâmetros, tipos de retorno, exemplos
Arquitetura	Como miniaturas incorporadas em base64 resolvem a restrição do sandbox do Cowork
MCP 2026-07-28	Suporte a duas eras: handshake legado e a revisão sem estado de um servidor, e como é verificado
Guia de Configuração CORS	Opcional, habilita carregamento direto de miniaturas por URL para galerias visualizadas no navegador

🦙 Pontuação Glama

Contribuindo

Contribuições são bem-vindas: correções de bugs, novas habilidades, ideias de recursos. Abra uma issue ou envie um PR.

Se o immich-photo-manager ajuda a gerenciar sua biblioteca, considere dar uma estrela no GitHub. Isso ajuda outras pessoas a descobrirem o projeto.

Suporte

Se o immich-photo-manager economizou seu tempo ou facilitou o gerenciamento da sua biblioteca de fotos, considere me comprar um café. Isso mantém o próximo projeto vindo!

Licença

Licença MIT: livre para usar, modificar e distribuir.

Forjado por Drolosoft · Ferramentas que desejamos que existissem