Claw2Immich

claw2immich es un servidor MCP (Protocolo de Contexto de Modelo) en Python que expone la aplicación de imágenes Immich seleccionada.

GitHub

Prueba este MCPPatrocinado

Documentación

claw2immich

claw2immich es un servidor MCP (Model Context Protocol) en Python que expone endpoints seleccionados de la API REST de Immich. Utiliza la especificación OpenAPI de Immich para los metadatos de la API y presenta un conjunto pequeño de herramientas conscientes de permisos para comprobaciones comunes de solo lectura.

Estado

El servidor MCP principal y el filtrado de capacidades están implementados.
La exposición de herramientas está controlada por los permisos de la API de Immich.
Las pruebas de integración cubren el listado de herramientas y las sondas de permisos.

Herramientas disponibles

ping_server
get_server_version
tool_access_report
write_capability_report
get_current_user (solo cuando lo permite la clave/token de API)
downloadAsset (solo cuando la clave/token de API está configurada; devuelve cargas útiles base64 seguras para transporte y admite el modo de entrega opcional immich_link)

Todos los endpoints de OpenAPI se exponen como herramientas denominadas immich_<operation> o immich_<method>_<path>. Las herramientas se filtran según la presencia de autenticación, marcadores de solo administrador y sondas de capacidad de escritura (por defecto POST /api/assets).

Las descripciones de herramientas de OpenAPI incluyen:

params: resumen de los campos obligatorios de ruta/consulta/cuerpo
example: breve bosquejo de llamada para entradas obligatorias
returns: título del esquema de respuesta y campos clave cuando estén disponibles

Las respuestas de herramientas de OpenAPI para activos, álbumes, personas y lugares incluyen un campo web_url con un enlace directo al elemento en la interfaz web de Immich (cuando IMMICH_EXTERNAL_DOMAIN está configurado o se descubre desde la configuración del servidor).

Los parámetros de herramientas de OpenAPI utilizan campos explícitos con prefijo para que los clientes MCP puedan descubrir qué configurar:

path_<name> para parámetros de ruta
query_<name> para parámetros de consulta
header_<name> para parámetros de cabecera
cookie_<name> para parámetros de cookie
body para cuerpos de solicitud JSON

Los campos heredados path_params, query_params, headers y json_body todavía se aceptan por compatibilidad.

downloadAsset está pensado para clientes que no pueden acceder directamente a la clave de API de Immich. El modo de entrega predeterminado es shared_link: el servidor devuelve un enlace tokenizado de corta duración (30 minutos) sin datos de carga útil en línea cuando la API de enlaces compartidos de Immich lo admite. Para la seguridad JSON de MCP, la entrega de carga útil en línea (inline_base64) permanece codificada en base64. El modo de compatibilidad opcional immich_link devuelve una URL autenticada directa de Immich.

Superficies de documentación MCP

Las instrucciones del servidor se envían durante la inicialización. Úsalas como guía rápida y consulta el recurso de guía de uso.
Las instrucciones de inicialización ahora mencionan el descubrimiento de externalDomain, grupos de flujo de trabajo, orientación de qué hacer/no hacer y una cadena de instrucciones de ejemplo.
Recurso: docs://usage-guide contiene una guía de flujo de trabajo detallada con ejemplos.
Prompts: hay plantillas de flujo de trabajo disponibles bajo títulos como "Immich: Get image", "Immich: Find person" e "Immich: Share album".

Configuración

Variables de entorno:

IMMICH_BASE_URL (por defecto http://localhost:2283)
IMMICH_API_KEY
IMMICH_API_TOKEN
IMMICH_EXTERNAL_DOMAIN (opcional: dominio para enlaces de interfaz web como https://immich.example.com; si no se establece, se descubre desde /api/server-config)
IMMICH_PROFILE (opcional: read_only, read_write o full_scope)
IMMICH_WRITE_PROBE_PATH (por defecto /api/assets)
IMMICH_WRITE_PROBE_METHOD (por defecto POST)
IMMICH_DOWNLOAD_ASSET_DELIVERY (opcional: shared_link (por defecto), inline_base64 o immich_link)

Variables de entorno del servidor MCP:

MCP_TRANSPORT (stdio, sse o streamable-http; por defecto stdio)
MCP_HOST (por defecto 127.0.0.1)
MCP_PORT (por defecto 8000)
MCP_MOUNT_PATH (ruta de montaje opcional para transporte SSE)
MCP_LOG_LEVEL (por defecto INFO)

Fuente de la especificación OpenAPI: Especificación con versión coincidente (después de /api/health y /api/server/version): https://raw.githubusercontent.com/immich-app/immich/v{VERSION}/open-api/immich-openapi-specs.json

Perfiles de acceso

Los perfiles de acceso proporcionan niveles de permisos predefinidos para simplificar la gestión de claves de API y reducir el riesgo de configuración incorrecta. Establece IMMICH_PROFILE a uno de los siguientes valores:

read_only

Caso de uso: Navegación segura, búsqueda y generación de informes sin riesgo de modificación.

Permisos requeridos:

asset.read - Ver fotos y videos
album.read - Ver álbumes
library.read - Explorar bibliotecas
timeline.read - Acceder a la línea de tiempo y recuerdos

Herramientas típicas expuestas:

immich_getAllAssets, immich_getAssetById, immich_searchAssets
immich_getAllAlbums, immich_getAlbumInfo
immich_getMyUserInfo, immich_getServerVersion
Todos los endpoints GET para lectura de datos

Herramientas bloqueadas:

Carga, actualización y eliminación de activos
Creación y modificación de álbumes
Gestión de usuarios
Configuración del servidor

Ejemplo de configuración de Claude Desktop (fragmento mcporter.json):

{
  "mcpServers": {
    "claw2immich-readonly": {
      "command": "python",
      "args": ["c:\\path\\to\\claw2immich\\main.py"],
      "env": {
        "IMMICH_BASE_URL": "https://immich.example.com",
        "IMMICH_API_KEY": "your-read-only-key",
        "IMMICH_PROFILE": "read_only"
      }
    }
  }
}

read_write

Caso de uso: Gestión completa de activos y álbumes sin privilegios de administrador.

Permisos requeridos:

Todos los permisos de read_only más:
asset.create - Subir fotos/videos
asset.update - Editar metadatos, favoritos
asset.delete - Eliminar activos
album.create - Crear álbumes
album.update - Modificar álbumes
album.delete - Eliminar álbumes

Herramientas típicas expuestas:

Todas las herramientas de solo lectura más:
immich_uploadAsset, immich_updateAsset, immich_deleteAssets
immich_createAlbum, immich_addAssetsToAlbum, immich_removeAssetFromAlbum
immich_updateUser (solo usuario propio)
Todos los endpoints POST, PUT, PATCH, DELETE excepto los de solo administrador

Herramientas bloqueadas:

Administración de usuarios (getAllUsers, createUser, deleteUser)
Configuración del servidor (setServerConfig, updateServerConfig)
Mantenimiento del sistema (runJobs, validateStorage)
Gestión de claves de API

Ejemplo de configuración de Claude Desktop:

{
  "mcpServers": {
    "claw2immich-readwrite": {
      "command": "python",
      "args": ["c:\\path\\to\\claw2immich\\main.py"],
      "env": {
        "IMMICH_BASE_URL": "https://immich.example.com",
        "IMMICH_API_KEY": "your-readwrite-key",
        "IMMICH_PROFILE": "read_write"
      }
    }
  }
}

full_scope

Caso de uso: Tareas administrativas, gestión de usuarios, configuración del servidor.

Permisos requeridos:

Todos los permisos de read_write más:
admin.user - Administración de usuarios
admin.config - Configuración del servidor
admin.jobs - Gestión de trabajos
admin.apiKey - Gestión de claves de API

Herramientas típicas expuestas:

Todas las herramientas de read_write más:
immich_getAllUsers, immich_createUser, immich_updateUser, immich_deleteUser
immich_getServerConfig, immich_updateServerConfig
immich_getAllJobs, immich_runJob
immich_createApiKey, immich_updateApiKey, immich_deleteApiKey

Ejemplo de configuración de Claude Desktop:

{
  "mcpServers": {
    "claw2immich-admin": {
      "command": "python",
      "args": ["c:\\path\\to\\claw2immich\\main.py"],
      "env": {
        "IMMICH_BASE_URL": "https://immich.example.com",
        "IMMICH_API_KEY": "your-admin-key",
        "IMMICH_PROFILE": "full_scope"
      }
    }
  }
}

Sin perfil (predeterminado)

Cuando IMMICH_PROFILE no está establecido, el filtrado de herramientas se basa únicamente en sondas de capacidad y los permisos reales de la clave de API. Esto es compatible con configuraciones existentes.

Pautas de selección de perfil:

Usa read_only para asistentes de IA que realizan búsquedas y análisis sin necesidad de modificaciones
Usa read_write para flujos de trabajo generales de gestión de activos y álbumes
Usa full_scope solo cuando se requiera acceso administrativo
Crea siempre una clave de API de Immich dedicada con permisos mínimos para cada perfil

Ejecución

python main.py

Script auxiliar: CLI de búsqueda inteligente

Para depuración local rápida sin configuración de cliente MCP, usa el script auxiliar:

python helper/smart_search_cli.py --list-envs
python helper/smart_search_cli.py --env .env --query "golden retriever on beach" --size 25 --order desc

Comportamiento:

Lista los archivos .env disponibles en el directorio actual (.env, .env_*).
Carga IMMICH_BASE_URL y IMMICH_API_KEY o IMMICH_API_TOKEN desde el archivo env seleccionado.
Llama a POST /api/search/smart e imprime la respuesta JSON directamente en stdout.

Pruebas

Las pruebas de integración usan el ejecutor unittest de la biblioteca estándar (pytest también puede descubrirlas).

Las razones de herramientas bloqueadas ahora incluyen detalles de estado HTTP o errores de red para ayudar a solucionar problemas de comprobación de capacidades.

Configuración de pruebas de integración:

Asegúrate de que un servidor Immich esté en ejecución y sea accesible.
Crea .env_test con credenciales de solo lectura.
Crea .env con credenciales de acceso completo, o establece IMMICH_ENV_FULL a otro archivo.

Las pruebas de cliente MCP inician un servidor en segundo plano usando SSE. Puedes anular los valores predeterminados:

MCP_TEST_HOST (por defecto 127.0.0.1)
MCP_TEST_PORT (por defecto 0 para asignación automática)
MCP_TEST_TIMEOUT (por defecto 20 segundos)
MCP_LOG_LEVEL (por defecto DEBUG para registros del servidor de prueba)

Ejecuta:

python -m unittest discover -s tests -v

Opcional con pytest:

pytest tests/

Puedes anular las ubicaciones de archivos env:

IMMICH_ENV_TEST para el archivo de credenciales restringidas (por defecto .env_test)
IMMICH_ENV_FULL para el archivo de credenciales de acceso completo (por defecto .env)

Pruebas de integración de acceso URL (test_integration_url_access.py)

Verifica que los campos web_url generados por la capa de decoración de URL sean accesibles contra una instancia de Immich en vivo (requiere credenciales de inicio de sesión de sesión además de una clave de API).

Crea .env_web en la raíz del proyecto (excluido por .gitignore):

IMMICH_BASE_URL=https://your-immich.example.com
IMMICH_API_KEY=<api-key-with-read-access>
IMMICH_EMAIL=<user@example.com>
IMMICH_PASSWORD=<your-password>

Variable	Propósito
`IMMICH_BASE_URL`	URL base de tu instancia de Immich
`IMMICH_API_KEY`	Clave de API para llamadas API autenticadas
`IMMICH_EMAIL`	Correo electrónico de la cuenta para `POST /api/auth/login`
`IMMICH_PASSWORD`	Contraseña de la cuenta para inicio de sesión de sesión

IMMICH_EXTERNAL_DOMAIN también puede incluirse para anular la base de decoración de URL; si se omite, recurre a la cadena de descubrimiento de /api/server-config.

Ejecuta:

pytest tests/test_integration_url_access.py -v

Las pruebas se omiten automáticamente cuando .env_web está ausente, el servidor es inaccesible o la instancia no tiene datos de ese tipo. Anula la ruta del archivo con IMMICH_ENV_WEB:

IMMICH_ENV_WEB=/path/to/other.env pytest tests/test_integration_url_access.py -v

Prueba	Endpoint	Patrón de URL esperado	Regresión para
`test_asset_web_url_accessible`	`GET /api/assets` (respaldo: `POST /api/search/assets`)	`.../photos/{id}`	—
`test_album_web_url_accessible`	`GET /api/albums`	`.../albums/{id}`	—
`test_person_web_url_accessible`	`GET /api/people`	`.../people/{id}` (no `/photos/{id}`)	elemento 49
`test_place_web_url_accessible`	`GET /api/places`	`.../explore...`	—
`test_newest_image_search_web_url_accessible`	`POST /api/search/assets`	`.../photos/{id}`	—
`test_random_person_web_url_accessible`	`GET /api/people` (selección aleatoria)	`.../people/{id}`	—
`test_random_album_web_url_accessible`	`GET /api/albums` (selección aleatoria)	`.../albums/{id}`	—
`test_random_video_web_url_accessible`	`POST /api/search/assets` tipo=VIDEO (selección aleatoria)	`.../photos/{id}`	—

Docker

Compilar y ejecutar localmente

Compila y ejecuta con Docker Compose:

docker compose build
docker compose up

Nota: el contenedor ejecuta main.py, que importa el paquete claw2immich. Si cambias la estructura del paquete, reconstruye la imagen para que el paquete actualizado se copie en el contenedor.

Las variables de entorno se pasan desde tu shell o archivo .env:

IMMICH_BASE_URL (por defecto http://host.docker.internal:2283)
IMMICH_API_KEY
IMMICH_API_TOKEN
IMMICH_WRITE_PROBE_PATH (por defecto /api/assets)
IMMICH_WRITE_PROBE_METHOD (por defecto POST)

Configuración del servidor MCP para Docker Compose:

MCP_TRANSPORT (por defecto sse en compose; usa streamable-http para HTTP)
MCP_HOST (por defecto 0.0.0.0 en compose)
MCP_PORT (por defecto 8000; publicado como puerto del host)

Usar imágenes precompiladas del Registro de Contenedores de GitHub

Las imágenes Docker precompiladas se publican automáticamente en el Registro de Contenedores de GitHub (GHCR) para cada push a las ramas main y develop, así como para versiones.

Descargar la imagen:

# Latest build from main branch
docker pull ghcr.io/joeru/claw2immich:latest

# Latest build from develop branch
docker pull ghcr.io/joeru/claw2immich:develop

# Specific version (e.g., 0.1.0)
docker pull ghcr.io/joeru/claw2immich:0.1.0

Ejecutar la imagen:

docker run -e IMMICH_BASE_URL=https://immich.example.com \
           -e IMMICH_API_KEY=your-api-key \
           -p 8000:8000 \
           ghcr.io/joeru/claw2immich:latest

Ejecutar con transporte SSE (HTTP):

docker run -e IMMICH_BASE_URL=https://immich.example.com \
           -e IMMICH_API_KEY=your-api-key \
           -e MCP_TRANSPORT=sse \
           -e MCP_HOST=0.0.0.0 \
           -p 8000:8000 \
           ghcr.io/joeru/claw2immich:latest

Ejecutar con perfil de solo lectura:

docker run -e IMMICH_BASE_URL=https://immich.example.com \
           -e IMMICH_API_KEY=your-readonly-api-key \
           -e IMMICH_PROFILE=read_only \
           -p 8000:8000 \
           ghcr.io/joeru/claw2immich:latest

Las imágenes admiten múltiples arquitecturas (amd64, arm64) y se seleccionan automáticamente según tu plataforma.