🌉 Forge Neo MCP

Servidor MCP para Stable Diffusion WebUI Forge - Neo · Genera imágenes en tu propia GPU, desde cualquier agente de IA que hable MCP

Pídele a Claude — o a cualquier agente compatible con MCP — una imagen, y la genera en tu Forge Neo local. Lee qué checkpoint está cargado, deduce los parámetros de muestreo y el estilo de prompt que espera ese modelo, escribe el prompt y te devuelve el archivo.

Nunca tienes que dictar pasos, CFG o sampler a menos que quieras. Esos provienen de tu propia configuración: los ajustes de tu instancia, tus generaciones pasadas, los metadatos de tu checkpoint. Cuando algo no se puede determinar, pregunta en lugar de adivinar.

[!IMPORTANT] Forge Neo debe ejecutarse con --api. No se instala nada en tu carpeta de Forge — ni extensión, ni nodo personalizado. El puente habla con la API REST que Forge ya expone.

📋 Tabla de contenidos

• Requisitos

• Instalación

• Configuración

• Primera ejecución

• Uso

• Herramientas

• Solución de problemas

• Lo que hace por ti

• Hoja de ruta

• Créditos

Related MCP server: Nano Banana

✅ Requisitos

Solo si Forge se ejecuta en otra máquina: acceso de red a él, y un recurso compartido de archivos si quieres resultados como rutas de archivo en lugar de base64.

📦 Instalación

1 · Activa la API en Forge Neo

Edita tu webui-user.bat (Windows) o webui-user.sh (Linux) y añade --api:

set COMMANDLINE_ARGS=--api

Conserva las banderas que ya tenías — solo añade --api. Reinicia Forge.

Comprueba que funciona: abre http://127.0.0.1:7860/docs. Si ves los endpoints /sdapi/v1/... listados, la API está activa.

2 · Instala el puente

pip install git+https://github.com/eduardoabreu81/forgeneo-mcp

3 · Regístralo con tu agente

Claude Code

claude mcp add forgeneo -e FORGE_URL=http://127.0.0.1:7860 -- forgeneo-mcp

Claude Desktop, Cursor o cualquier cliente con un mcp.json

{
  "mcpServers": {
    "forgeneo": {
      "command": "forgeneo-mcp",
      "env": { "FORGE_URL": "http://127.0.0.1:7860" }
    }
  }
}

Reinicia tu cliente — los servidores MCP se cargan al inicio, así que las herramientas aparecen en una nueva sesión.

⚙️ Configuración

Todo es opcional excepto FORGE_URL, y eso solo si Forge no está en 127.0.0.1:7860.

Todo en una sola máquina

No hay nada más que hacer — los valores por defecto lo cubren.

Forge en otra máquina

Inicia Forge con --listen --api, luego apunta el puente hacia él y mapea sus rutas:

claude mcp add forgeneo \
  -e FORGE_URL=http://gpu-box:7860 \
  -e FORGE_PATH_MAP='D:/forge-neo=//gpu-box/share/forge-neo' \
  -- forgeneo-mcp

FORGE_PATH_MAP se lee como cómo lo llama Forge = cómo lo llamas tú. Forge reporta rutas como D:\forge-neo\output\...; si accedes a esa misma carpeta como \\gpu-box\share\forge-neo\output\..., ese mapeo permite que el puente te entregue rutas de archivo en lugar de megabytes de base64.

Sin él, todo sigue funcionando — solo obtienes base64.

[!NOTE] --listen expone la API a tu red sin contraseña. Si eso importa donde estás, añade --api-auth usuario:contraseña a Forge y configura FORGE_AUTH para que coincida.

🚀 Primera ejecución

Abre una nueva sesión y pídele a tu agente que verifique la conexión. Llama a capabilities e informa lo que encontró:

reachable    true
counts       checkpoints · loras · samplers · schedulers · modules
filesystem   file paths        (or: base64 — no readable output dir)
history      how many past generations it could read

Tres cosas que vale la pena revisar:

• filesystem: base64 — falta FORGE_PATH_MAP o es incorrecto. No es fatal, pero los resultados inflarán tu conversación.

• history: 0 — no puede aprender de tu trabajo pasado. Normalmente la carpeta de salida es inaccesible, o Forge no guarda metadatos (ver Solución de problemas).

• loras: 0 con LoRAs instalados — la lista de LoRAs de Forge está vacía; actualízala en la interfaz.

💬 Uso

Solo pregunta. El agente se encarga del resto.

"una imagen de portada para un post sobre senderismo invernal"

Comprueba qué está cargado, ve si ese modelo prefiere prosa o etiquetas, escribe el prompt en consecuencia y genera.

"lo mismo pero en el estilo que uso para miniaturas"

Busca entre tus LoRAs, encuentra el que quieres decir, toma su palabra de activación y el peso que normalmente usas, y lo escribe en el prompt — visiblemente, para que puedas leer lo que se envió.

"cambia a mi modelo de retratos"

Carga ese checkpoint. Si pertenece a una arquitectura diferente, el VAE y el codificador de texto correspondientes vienen con él.

Otras cosas que vale la pena preguntar directamente:

• "¿qué modelo está cargado y cómo debo hacerle el prompt?" — el perfil, en términos simples

• "¿cuáles de mis LoRAs funcionan con este checkpoint?" — filtrado a los compatibles

• "¿mi configuración de flux está completa?" — verifica el VAE y los codificadores de texto

• "detente" — interrumpe una generación en curso

🛠️ Herramientas

Tu agente las elige por sí mismo; la lista está aquí para que sepas qué puede hacer.

🔧 Solución de problemas

Dice que no puede alcanzar Forge Confirma que Forge se está ejecutando con --api y que http://127.0.0.1:7860/docs lista los endpoints /sdapi/v1/. Si Forge está en otra máquina, también necesita --listen, y un firewall puede estar bloqueando.

Los resultados vuelven como base64 e inundan la conversación Falta FORGE_PATH_MAP o no coincide. Compara la ruta que reporta Forge — visible en la información de cualquier generación — con la ruta que usas para acceder a la misma carpeta.

No conoce mis ajustes habituales Aprende de tus imágenes pasadas, lo que requiere que Forge guarde los parámetros de generación. En Settings → Saving images, mantén habilitada la opción "Save text information about generation parameters as chunks to png files", o activa el archivo .txt adjunto. Sin ninguno, tus salidas no llevan parámetros y recurre a los valores por defecto de la arquitectura.

Sigue preguntando a qué linaje pertenece mi checkpoint SDXL Pony, Illustrious, Animagine y SDXL estándar son indistinguibles del archivo — mismos tensores, mismo preset, diferente vocabulario de prompt. Responde una vez; se recuerda por archivo y nunca se vuelve a preguntar.

Las imágenes se ven mal después de cambiar de arquitectura Pide una verificación de módulos. Forge recuerda el último VAE y codificador de texto seleccionados bajo cada preset, así que cargar un checkpoint mientras otro preset estaba activo puede dejar los incorrectos adjuntos. La verificación nombra lo que falta y si el archivo correcto ya está instalado.

Se rechazó una descarga por falta de espacio Es deliberado — comprueba el espacio libre antes de comenzar en lugar de fallar varios gigabytes después. Libera algo de espacio, o elige una compilación más ligera como fp8_scaled en lugar de bf16.

🎯 Lo que hace por ti

• Parámetros de muestreo que se ajustan al modelo. Tomados de tus propias generaciones pasadas cuando están disponibles, y de la configuración de tu instancia en caso contrario — no de una tabla en este repositorio.

• El vocabulario de prompt correcto. Etiquetas de calidad donde ayudan, ninguna donde perjudican: añadir masterpiece, best quality a un modelo entrenado con subtítulos diluye el prompt en lugar de mejorarlo.

• Tus LoRAs, buscables. Por nombre, etiqueta, palabra de activación o descripción, con los pesos que realmente usas. Nada se añade a un prompt sin mostrártelo.

• Incertidumbre honesta. Cuando la evidencia se agota, lo dice y pregunta. Sin adivinanzas silenciosas.

• Verificaciones de salud de módulos. Nota cuando un preset ha tomado el VAE o codificador de texto incorrecto, y señala la descarga oficial para cualquier cosa que falte.

Las notas sobre cómo se deriva cada respuesta viven en el código fuente, junto al código que la deriva.

🗺️ Hoja de ruta

• Video (Wan) — Forge genera video mediante conteos de fotogramas en múltiplos de 4n+1 y codifica con ffmpeg, pero la API descarta la ruta resultante. Recoger desde el disco ya es como vuelven las imágenes, así que esto es principalmente plomería.

• Metadatos EXIF — JPEG y WebP almacenan parámetros en EXIF cuando el archivo .txt está desactivado; esa combinación actualmente no produce historial.

• Autenticación — FORGE_AUTH está implementado pero no se ha probado contra una instancia real de --api-auth.

📄 Créditos

• Forge Neo por Haoming02 — la WebUI a la que este puente se conecta, y la wiki de Download Models detrás de la referencia de módulos

• Autores de modelos que publican guías reales de prompting en sus tarjetas — la tabla de dialectos se construye a partir de esas, no de suposiciones

• Model Context Protocol — el protocolo y el SDK de Python

• CivitAI — endpoint público por hash utilizado por la búsqueda opcional

📜 Licencia

MIT — ver LICENSE

Hecho con ❤️ para la comunidad de Stable Diffusion

Reportar un error • Solicitar una función • Discusiones • ☕ Ko-fi