imagine-mcp

Comprensión y generación de imágenes y videos

Documentación

imagine-mcp

mcp-name: io.github.n24q02m/imagine-mcp

Comprensión y generación de imágenes y videos para agentes de IA -- en Gemini, OpenAI y Grok.

Proyectos hermanos de n24q02m (haga clic para expandir)

Proyecto	Lema	Etiqueta
agent-chat-plugin	Agentes de IA pares chatean en una carpeta compartida — sin relevo humano, sin orquestador, tra...	Herramientas
better-code-review-graph	Grafo de conocimiento para revisiones de código eficientes en tokens -- búsqueda semántica y llamadas-...	MCP
better-drive	Sincronización bidireccional de Google Drive con filtro .driveignore — motor rclone, bandeja de Windows	Herramientas
better-email-mcp	Correo IMAP/SMTP para agentes de IA -- leer, enviar, organizar carpetas y gestionar archivos adjuntos...	MCP
better-godot-mcp	Servidor MCP compuesto para Godot Engine -- 17 herramientas compuestas para desarrollo asistido por IA...	MCP
better-notion-mcp	Notion centrado en Markdown para agentes de IA -- páginas, bases de datos, bloques y comentarios...	MCP
better-semantic-release	Fork de python-semantic-release con guardas de seguridad de lanzamiento integradas (orp...	Herramientas
better-telegram-mcp	Telegram para agentes de IA -- mensajes, chats, medios y contactos en ambos bo...	MCP
better-workspace-mcp	Servidor MCP de Google Workspace (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...	MCP
claude-plugins	Mercado de plugins de Claude Code para los servidores MCP de n24q02m -- instalar búsqueda web...	Mercado
imagine-mcp	Comprensión y generación de imágenes y videos para agentes de IA -- en Gemini, Op...	MCP
jules-task-archiver	Extensión de Chrome para operaciones masivas en tareas de Jules mediante la API batchexecute -- a...	Herramientas
mcp-core	Base compartida para construir servidores MCP -- transporte HTTP Streamable, OAut...	MCP
mnemo-mcp	Memoria de IA persistente con búsqueda híbrida y sincronización integrada. Abierta, gratuita, ilimitada...	MCP
qwen3-embed	Embedding de texto Qwen3 ligero y reordenamiento mediante ONNX Runtime y GGUF	Biblioteca
skret	Secretos sin servidor.	CLI
tacet	Una cascada neuro-simbólica auto-destilante que amortiza el costo de LLM en conocimiento...	Herramientas
web-core	Paquete de infraestructura web compartida para búsqueda, scraping, seguridad HTTP y st...	Biblioteca
wet-mcp	Servidor MCP de código abierto para agentes de IA: búsqueda web, extracción de contenido y lib...	MCP

Características

Comprensión multimodal -- Describir, clasificar o razonar sobre imágenes y videos (Gemini maneja imagen + video mixtos en una sola llamada)
Generación de imágenes -- Texto a imagen e imagen a imagen (editar / inpaint) en Gemini Imagen, OpenAI gpt-image, Grok Imagine
Generación de videos -- Texto a video e imagen a video (Gemini Veo 3.1, Grok Imagine Video)
3 proveedores x 2 niveles -- Misma interfaz para gemini / openai / grok en poor (barato/rápido) o rich (alta calidad); cambiar mediante parámetro
Paso directo de modelo abierto -- La comprensión se enruta a través de litellm; pase cualquier provider/model, o configure una cadena de modelos ordenada (sin catálogo fijo)
Modo degradado -- El servidor se inicia sin credenciales y muestra los proveedores restantes a medida que agrega claves
Caché de respuestas -- Caché en disco de respuestas understand con TTL configurable
Transporte dual -- stdio puro con variables de entorno del proveedor (predeterminado) o HTTP multiusuario con formulario de relevo de token de pegado

Instalación

Ejecute con uvx (sin paso de instalación) o extraiga la imagen del contenedor:

# uvx -- recommended, runs the published PyPI package
uvx imagine-mcp

# Docker
docker run -it --rm ghcr.io/n24q02m/imagine-mcp:latest

Agréguelo a un cliente MCP apuntando el cliente al comando uvx imagine-mcp y proporcionando al menos una clave de proveedor (ver Configuración):

{
  "mcpServers": {
    "imagine": {
      "command": "uvx",
      "args": ["imagine-mcp"],
      "env": { "GEMINI_API_KEY": "AIza..." }
    }
  }
}

Para fragmentos por cliente (Claude Code, Codex, Gemini CLI, Cursor, Windsurf) y la configuración HTTP basada en navegador, consulte la documentación de configuración.

Instalar con un agente de IA -- pegue esto a su agente de codificación de IA:

Instale el servidor MCP imagine-mcp siguiendo los pasos en https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/imagine-mcp/setup-with-agent.md

Smithery

imagine-mcp incluye un smithery.yaml para que pueda instalarse y ejecutarse a través de Smithery. La entrada lanza el paquete PyPI publicado sobre stdio (uvx --python 3.13 imagine-mcp) con un esquema de configuración vacío -- no se requieren campos de configuración en el momento del despliegue. Las claves del proveedor se suministran en tiempo de ejecución a través del flujo de credenciales del propio servidor (variables de entorno en modo stdio, o el formulario de configuración del navegador en modo HTTP; ver Configuración).

Configuración

Dos transportes (por defecto stdio; opte por http con --http, MCP_TRANSPORT=http o TRANSPORT_MODE=http):

stdio (predeterminado) -- usuario único, lee credenciales solo de variables de entorno. Sale si ninguna de las tres claves de proveedor está configurada.
http -- demonio HTTP. Autoalojamiento local en 127.0.0.1 por defecto, o remoto multiusuario (aislamiento de credenciales por JWT-sub) cuando PUBLIC_URL + MCP_DCR_SERVER_SECRET están configurados. En modo HTTP, las credenciales se ingresan a través de un formulario del navegador en /authorize.

Claves de proveedor

Todas opcionales -- el servidor se inicia en modo degradado y muestra los proveedores que tengan una clave. Configure al menos una.

Variable de entorno	Proveedor	Obtenga una clave en
`GEMINI_API_KEY`	Gemini (image + video)	aistudio.google.com/apikey
`OPENAI_API_KEY`	OpenAI (image)	platform.openai.com/api-keys
`XAI_API_KEY`	Grok / xAI (image + video)	console.x.ai

Cuando se llama a una herramienta sin un provider explícito, la primera clave presente gana en el orden XAI_API_KEY -> OPENAI_API_KEY -> GEMINI_API_KEY.

Cadenas de modelos (opcional)

La elección del modelo pasa directamente a litellm (understand) o al SDK nativo del proveedor (generate) -- no hay un catálogo de modelos fijo. Cada cadena es un CSV de entradas provider/model de litellm; el orden es el orden de respaldo.

Variable de entorno	Propósito
`UNDERSTAND_MODELS`	Cadena de modelos ordenada para `understand` (respaldo de litellm). Vacía y sin `model` explícito -> `understand` falla de forma ruidosa (sin valor predeterminado integrado).
`GENERATE_MODELS`	Cadena de modelos ordenada para `generate`. La primera entrada selecciona el proveedor nativo + modelo. Vacía -> el valor predeterminado mínimo integrado del proveedor.
`GENERATE_PROVIDER_PRIORITY`	CSV de nombres de proveedores que reordenan el respaldo automático de generación. Por defecto a `grok,openai,gemini`.

La comprensión se enruta a través de litellm (passthrough provider/model), por lo que cualquier proveedor de litellm funciona -- suministre el <PROVIDER>_API_KEY de ese proveedor. La generación permanece en los SDK nativos del proveedor (Gemini, OpenAI, Grok). Ejemplo:

{
  "mcpServers": {
    "imagine": {
      "command": "uvx",
      "args": ["imagine-mcp"],
      "env": {
        "UNDERSTAND_MODELS": "gemini/<model-id>,openai/<model-id>",
        "GEMINI_API_KEY": "AIza...",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Perillas de tiempo de ejecución

config(action="set", key=..., value=...) ajusta log_level, default_provider, default_tier y cache_ttl_seconds en tiempo de ejecución.

CLI

El comando de consola imagine-mcp instalado por el paquete no toma subcomandos -- inicia el servidor MCP directamente. El transporte se selecciona mediante una sola bandera o sus equivalentes de variables de entorno:

imagine-mcp            # stdio transport (default); reads provider keys from env vars
imagine-mcp --http     # HTTP daemon; credentials via the browser setup form

Invocación	Entorno equivalente	Resultado
`imagine-mcp`	`MCP_TRANSPORT` sin configurar	stdio, usuario único, credenciales de variables de entorno
`imagine-mcp --http`	`MCP_TRANSPORT=http` (o `TRANSPORT_MODE=http`)	demonio HTTP -- autoalojamiento local `127.0.0.1`, o remoto multiusuario cuando `PUBLIC_URL` + `MCP_DCR_SERVER_SECRET` están configurados

En modo stdio, el servidor sale si ninguna de las claves de proveedor está configurada. Las perillas de enlace HTTP remoto (MCP_HOST, MCP_PORT) se aplican solo cuando PUBLIC_URL está configurado; ver Configuración.

Remoto (modo HTTP)

Un despliegue HTTP sirve a clientes que soportan servidores MCP HTTP remotos. Está protegido por OAuth -- una solicitud no autenticada devuelve 401 con un desafío WWW-Authenticate: Bearer -- y las credenciales se provisionan a través del formulario de configuración del navegador. Apunte un cliente MCP compatible con HTTP a https://<your-host>/mcp y complete el flujo OAuth para conectarse. Para poner uno en marcha, ver Desplegar en Cloudflare.

Documentación

Documentación completa en mcp.n24q02m.com/servers/imagine-mcp/setup/:

Configuración -- métodos de instalación para Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
Resumen de modos -- stdio / relevo local / relevo remoto / oauth remoto
Configuración multiusuario -- modelo de credenciales por JWT-sub

Herramientas

Herramienta	Acciones	Descripción
`understand`	--	Describir o razonar sobre una o más URLs de imagen/video. `media_urls: list[str]`, `prompt: str`, `provider`, `tier`, `max_tokens`.
`generate`	--	Generar una imagen o video a partir de un prompt de texto. `media_type: image\|video`, opcional `reference_image_url`, opcional `job_id` (sondeo de video), `aspect_ratio`, `duration_seconds`.
`config`	`setup_status`, `setup_skip`, `setup_reset`, `setup_complete`, `warmup`, `status`, `set`, `cache_clear` (`relay_status`/`relay_skip`/`relay_reset`/`relay_complete` honrados como alias obsoletos)	Configuración de credenciales + tiempo de ejecución: verificar estado de credenciales, configurar perillas de tiempo de ejecución (nivel de registro, proveedor predeterminado, TTL), limpiar caché de respuestas.
`help`	--	Documentación completa en Markdown para temas `understand`, `generate` o `config`.
`config__open_relay`	--	Helper inyectado por el framework (mcp-core); abre el formulario de credenciales del navegador.

La elección del modelo es impulsada por el llamador (passthrough de litellm provider/model o una cadena de entorno *_MODELS) -- ver Cadenas de modelos arriba.

Comparación

Cómo se compara imagine-mcp con los competidores directos en cada pilar:

Capacidad	imagine-mcp	EverArt MCP	fal.ai MCP	Replicate Flux MCP
Comprensión de imagen/video	Sí (describe / clasifica / razona sobre URLs de imagen + video)	No	No	No
Generación de imágenes	Sí (texto a imagen + imagen a imagen vía `reference_image_url`)	Sí (único `generate_image`)	Sí (texto/imagen a imagen, edición, inpaint)	Sí (único `generate_image`)
Generación de video	Sí (texto a video + imagen a video, sondeo asíncrono `job_id`)	No	Sí (texto/imagen a video)	No
Backends multi-proveedor	Sí (Gemini / OpenAI / Grok, con respaldo automático)	No (solo EverArt)	No (solo fal.ai)	No (solo Replicate Flux)
Niveles de calidad/costo	Sí (`poor` barato-rápido vs `rich` alta calidad por proveedor)	No	No	No
Auto-alojable / código abierto	Sí (Apache-2.0, stdio + HTTP auto-alojado)	Sí (MIT, archivado)	Sí (MIT)	Sí (MIT, archivado)

Seguridad

Prevención de SSRF + LFI -- Todos los media_urls y reference_image_url se validan en el límite de despacho; solo los esquemas http:// y https:// llegan a los proveedores. file://, ftp://, gopher:// y las URLs sin esquema son rechazadas.
Sin credenciales en errores -- Los errores del lado del proveedor se sanean antes de devolverse.
Inicio degradado -- La falta de credenciales no impide que el servidor se inicie; las acciones afectadas muestran errores accionables en lugar de fallar al arrancar.
Almacenamiento de credenciales -- Las credenciales enviadas a través del formulario de credenciales del navegador se almacenan cifradas mediante mcp-core (AES-GCM, clave vinculada a la máquina) en ~/.imagine-mcp/config.json.

Nombre de usuario del espacio de trabajo (formulario de configuración HTTP)

El formulario de credenciales del navegador tiene un campo opcional de nombre de usuario del espacio de trabajo. Introducir el mismo nombre de usuario siempre te lleva al mismo bucket por sub, por lo que tus claves de proveedor permanecen accesibles a través de una reautorización y entre dispositivos, en lugar de estar vinculadas al sujeto único emitido para cada ida y vuelta de /authorize. Dejarlo en blanco mantiene el comportamiento anterior de autorización por sesión.

Límite de confianza: cuando el formulario está protegido por un MCP_RELAY_PASSWORD compartido, el nombre de usuario es una clave de partición, no un secreto: cualquiera que conozca esa contraseña puede escribir cualquier nombre de usuario y llegar a ese bucket. Eso está bien para un grupo de confianza; un despliegue multi-tenant no confiable necesita un secreto por usuario o OAuth delegado en su lugar.

Migración única: los usuarios existentes deben volver a introducir sus credenciales una vez después de este cambio. No se elimina nada; las credenciales almacenadas bajo el antiguo sujeto aleatorio simplemente ya no se abordan.

Compilar desde el código fuente

git clone https://github.com/n24q02m/imagine-mcp.git
cd imagine-mcp
mise run setup      # or: uv sync --group dev
mise run dev        # run the server in stdio mode (add --http for the HTTP daemon)

Desplegar en Cloudflare

Ejecuta tu propia instancia de imagine sin servidor en Cloudflare (Worker + Container + KV). El almacenamiento es solo KV: la bóveda de credenciales por usuario vive en KV, y la generación devuelve solo base64 porque el sistema de archivos del contenedor es efímero (IMAGINE_OUTPUT_MODE=base64).

Requisitos: una cuenta de Cloudflare en el plan Workers de pago -- requerido para Containers (el nivel gratuito de Cloudflare no incluye Containers) -- y el CLI wrangler.

git clone https://github.com/n24q02m/imagine-mcp && cd imagine-mcp
wrangler login
Crea el espacio de nombres KV (imagine es solo KV -- sin D1 ni Vectorize), luego pega el id devuelto en wrangler.jsonc (el marcador de posición <imagine-kv-namespace-id>):
```
wrangler kv namespace create imagine-kv
```

Sube la imagen del contenedor a tu registro gestionado de Cloudflare (los Containers de CF no pueden extraer de registros externos directamente), luego establece <YOUR_ACCOUNT_ID> en wrangler.jsonc:

docker pull ghcr.io/n24q02m/imagine-mcp:beta
docker tag ghcr.io/n24q02m/imagine-mcp:beta imagine-mcp:beta
wrangler containers push imagine-mcp:beta   # prints registry.cloudflare.com/<ACCOUNT_ID>/imagine-mcp:beta

Apunta los marcadores de posición wrangler.jsonc restantes a tu propio dominio: <YOUR_PUBLIC_URL> (el vars.PUBLIC_URL, p. ej. https://imagine.example.com) y <YOUR_WORKER_DOMAIN> (el patrón de dominio personalizado routes, p. ej. imagine.example.com).
Establece los secretos. CREDENTIAL_SECRET (clave de firma JWT estable + clave de bóveda por usuario) y MCP_DCR_SERVER_SECRET (prueba de un despliegue multi-usuario intencional) son obligatorios; MCP_RELAY_PASSWORD controla el inicio de sesión del formulario de configuración del navegador. Las claves de proveedor son opcionales por defecto del servidor: los usuarios normalmente pegan las suyas a través del formulario de configuración en su lugar:
```
wrangler secret put CREDENTIAL_SECRET
wrangler secret put MCP_DCR_SERVER_SECRET
wrangler secret put MCP_RELAY_PASSWORD
wrangler secret put GEMINI_API_KEY       # optional provider default
wrangler secret put OPENAI_API_KEY       # optional provider default
wrangler secret put XAI_API_KEY          # optional provider default
```
wrangler deploy, luego abre tu dominio de Worker y termina la configuración en el formulario de relevo del navegador.

La imagen de contenedor http ya se ejecuta multi-usuario (MCP_TRANSPORT=http está integrado en el objetivo de imagen). El almacenamiento se asigna a Cloudflare mediante MCP_STORAGE_BACKEND=cf-kv (bóveda de credenciales cifrada) con IMAGINE_OUTPUT_MODE=base64, que fuerza respuestas base64 para que no se escriba ninguna ruta de medios en el sistema de archivos efímero del contenedor.

Modelo de confianza

Este plugin implementa TC-Local (vinculado a la máquina, un único principal de confianza). Consulta el modelo de confianza de mcp-core para la clasificación completa.

Modo	Almacenamiento	Cifrado	¿Quién puede leer tus datos?
stdio (predeterminado)	`~/.imagine-mcp/config.json`	AES-GCM, clave vinculada a la máquina	Solo tu usuario del SO (permiso de archivo 0600)
HTTP auto-alojado	Igual que stdio	Igual	Solo tú (admin = usuario)

Contribuir

Consulta CONTRIBUTING.md para el flujo de trabajo de desarrollo completo, la convención de commits y el proceso de lanzamiento. Issues + Discussions son bienvenidos.

Licencia

Apache-2.0 -- consulta LICENSE.