Forge Neo MCP
Bridge any MCP-capable agent to your local Forge Neo instance so it can inspect models and generate images on your own GPU.
Inspect the setup —
capabilitiesreports routes, counts and readable metadata sources;model_profiledescribes the loaded checkpoint, its sampling parameters and prompt style.Prompt correctly —
prompt_dialectreturns the model's expected vocabulary and quality tags, asking once when a lineage is ambiguous and caching the answer.Work with LoRAs —
lorassearches by name, tag, trigger word or description;lora_inforeturns full details plus a ready-to-paste prompt fragment.Manage checkpoints —
modelslists, loads or refreshes checkpoints, switching preset, VAE and text encoder when the architecture changes.Keep modules healthy —
module_checkverifies VAE and text encoders match the architecture;module_downloadshows where missing files come from and fetches only on explicit confirmation.Generate images —
generateruns txt2img or img2img from a verbatim prompt, filling unset sampling parameters from the model's own history or architecture defaults.Control jobs —
progresschecks, interrupts or skips the running generation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Forge Neo MCP generate a cyberpunk cat portrait in your style"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🌉 Forge Neo MCP
MCP server for Stable Diffusion WebUI Forge - Neo · Generate images on your own GPU, from any AI agent that speaks MCP
Ask Claude — or any MCP-capable agent — for an image, and it generates on your local Forge Neo. It reads which checkpoint is loaded, works out the sampling parameters and prompt style that model expects, writes the prompt, and hands you back the file.
You never have to dictate steps, CFG or sampler unless you want to. Those come from your own setup: your instance's settings, your past generations, your checkpoint's metadata. Where something cannot be determined, it asks instead of guessing.
Forge Neo must run with--api. Nothing is installed into your Forge folder — no extension, no custom node. The bridge talks to the REST API that Forge already exposes.
📋 Table of Contents
Related MCP server: sd-api-mcp
✅ Requirements
Forge Neo | running with |
Python | 3.10 or newer, on the machine running the agent |
An MCP client | Claude Code, Claude Desktop, Cursor, or anything else that speaks MCP |
Only if Forge runs on a different machine: network access to it, and a file share if you want results as file paths rather than base64.
📦 Installation
1 · Turn on the API in Forge Neo
Edit your webui-user.bat (Windows) or webui-user.sh (Linux) and add --api:
set COMMANDLINE_ARGS=--apiKeep whatever flags you already had — just append --api. Restart Forge.
Check it worked: open
http://127.0.0.1:7860/docs. If you see/sdapi/v1/...endpoints listed, the API is on.
2 · Install the bridge
pip install git+https://github.com/eduardoabreu81/forgeneo-mcp3 · Register it with your agent
Claude Code
claude mcp add forgeneo -e FORGE_URL=http://127.0.0.1:7860 -- forgeneo-mcpClaude Desktop, Cursor, or any client with an mcp.json
{
"mcpServers": {
"forgeneo": {
"command": "forgeneo-mcp",
"env": { "FORGE_URL": "http://127.0.0.1:7860" }
}
}
}Restart your client — MCP servers load at startup, so the tools appear in a new session.
⚙️ Configuration
Everything is optional except FORGE_URL, and even that only if Forge is not at 127.0.0.1:7860.
Variable | What it does | Default |
| Where Forge is |
|
|
| none |
| Translates Forge's paths into ones your machine can reach | none |
| Your output folder, if it cannot be found automatically | auto |
| Seconds to wait on a request |
|
| How many recent images to read when learning your settings |
|
|
| off |
| Where your confirmed answers are remembered |
|
Everything on one machine
Nothing else to do — the defaults cover it.
Forge on another machine
Start Forge with --listen --api, then point the bridge at it and map its paths:
claude mcp add forgeneo \
-e FORGE_URL=http://gpu-box:7860 \
-e FORGE_PATH_MAP='D:/forge-neo=//gpu-box/share/forge-neo' \
-- forgeneo-mcpFORGE_PATH_MAP reads as what Forge calls it = what you call it. Forge reports paths like D:\forge-neo\output\...; if you reach that same folder as \\gpu-box\share\forge-neo\output\..., that mapping lets the bridge hand you file paths instead of megabytes of base64.
Without it everything still works — you just get base64.
--listen exposes the API to your network with no password. If that matters where you are, add --api-auth user:password to Forge and set FORGE_AUTH to match.
🚀 First run
Open a new session and ask your agent to check the connection. It calls capabilities and reports what it found:
reachable true
counts checkpoints · loras · samplers · schedulers · modules
filesystem file paths (or: base64 — no readable output dir)
history how many past generations it could readThree things worth a glance:
filesystem: base64—FORGE_PATH_MAPis missing or wrong. Not fatal, but results will bloat your conversation.history: 0— it cannot learn from your past work. Usually the output folder is unreachable, or Forge is saving no metadata (see Troubleshooting).loras: 0with LoRAs installed — Forge's own LoRA list is empty; refresh it in the UI.
💬 Using it
Just ask. The agent handles the rest.
"a cover image for a post about winter hiking"
It checks what is loaded, sees whether that model wants prose or tags, writes the prompt accordingly, and generates.
"same thing but in the style I use for thumbnails"
It searches your LoRAs, finds the one you mean, picks up its trigger word and the weight you normally use, and writes it into the prompt — visibly, so you can read what was sent.
"switch to my portrait model"
It loads that checkpoint. If it belongs to a different architecture, the matching VAE and text encoder come with it.
Other things worth asking directly:
"what model is loaded and how should I prompt it?" — the profile, in plain terms
"which of my LoRAs work with this checkpoint?" — filtered to compatible ones
"is my flux setup complete?" — checks the VAE and text encoders
"stop" — interrupts a running generation
🛠️ Tools
Your agent picks these on its own; the list is here so you know what it can do.
Tool | Purpose |
| What this instance offers and what the bridge could read |
| The loaded checkpoint: parameters, prompt style, module health |
| How this model expects to be prompted, with its quality tags |
| Search your LoRAs by name, tag, trigger word or description |
| Everything about one LoRA, with a ready prompt fragment |
| List, load or refresh checkpoints |
| Whether the loaded VAE and text encoders suit the architecture |
| Where a missing module comes from — fetches only if you approve |
| Generate from a written prompt, txt2img or img2img |
| Check, interrupt or skip the running job |
🔧 Troubleshooting
It says it cannot reach Forge
Confirm Forge is running with --api and that http://127.0.0.1:7860/docs lists /sdapi/v1/ endpoints. If Forge is on another machine it also needs --listen, and a firewall may be in the way.
Results come back as base64 and flood the conversation
FORGE_PATH_MAP is missing or does not match. Compare the path Forge reports — visible in any generation's info — with the path you use to reach the same folder.
It does not know my usual settings
It learns from your past images, which needs Forge to save generation parameters. In Settings → Saving images, keep "Save text information about generation parameters as chunks to png files" enabled, or turn on the .txt sidecar. With neither, your outputs carry no parameters and it falls back to architecture defaults.
It keeps asking which lineage my SDXL checkpoint is Pony, Illustrious, Animagine and stock SDXL are indistinguishable from the file — same tensors, same preset, different prompt vocabulary. Answer once; it is remembered per file and never asked again.
Images look wrong after switching architecture Ask for a module check. Forge remembers the last VAE and text encoder selected under each preset, so loading a checkpoint while another preset was active can leave the wrong ones attached. The check names what is missing and whether the right file is already installed.
A download was refused for lack of space
Deliberate — it checks free space before starting rather than failing several gigabytes in. Free some room, or pick a lighter build such as fp8_scaled instead of bf16.
🎯 What it does for you
Sampling parameters that fit the model. Taken from your own past generations where available, and from your instance's settings otherwise — not from a table in this repo.
The right prompt vocabulary. Quality tags where they help, none where they hurt: adding
masterpiece, best qualityto a model trained on captions dilutes the prompt rather than improving it.Your LoRAs, searchable. By name, tag, trigger word or description, with the weights you actually use. Nothing is added to a prompt without showing you.
Honest uncertainty. Where the evidence runs out it says so and asks. No silent guesses.
Module sanity checks. Notices when a preset has picked up the wrong VAE or text encoder, and points at the official download for anything missing.
Notes on how each answer is derived live in the source, next to the code that derives it.
🗺️ Roadmap
Video (Wan) — Forge generates video through frame counts in multiples of
4n+1and encodes with ffmpeg, but the API discards the resulting path. Collecting from disk is already how images come back, so this is mostly plumbing.EXIF metadata — JPEG and WebP store parameters in EXIF when the
.txtsidecar is off; that combination currently yields no history.Authentication —
FORGE_AUTHis implemented but has not been exercised against a live--api-authinstance.
📄 Credits
Forge Neo by Haoming02 — the WebUI this bridges to, and the Download Models wiki behind the module reference
Model authors who publish real prompting guidance on their cards — the dialect table is built from those, not from guesswork
Model Context Protocol — the protocol and Python SDK
CivitAI — public by-hash endpoint used by the optional lookup
📜 License
MIT — see LICENSE
Made with ❤️ for the Stable Diffusion community
Report Bug • Request Feature • Discussions • ☕ Ko-fi
More Forge Neo extensions at eduardoabreu81.github.io
Available Tools
10 toolscapabilitiesA
Report what this Forge instance offers: routes, counts, and which metadata sources are available. Call this first in a session.
Inputs: no named parameters.
generateA
Generate an image from an already-written prompt.
The prompt is sent verbatim: include any <lora:name:weight> yourself. With
use_profile_defaults on, missing sampling parameters are filled from what the
loaded model actually used before, so leave them unset unless you mean to
override. That includes shift (Forge's distilled_cfg_scale) and the
dimensions: leaving them at 0 takes the architecture's own values instead of
a generic default. Returns file paths when the output folder is readable.
Pass init_image (a local file path) to run img2img instead, where
denoising_strength controls how far the result may drift from it: around
0.3 keeps the composition, 0.75 reinterprets it freely. Edit-style and video
models expect values close to 1.0.
Inputs: prompt (required), seed, shift, steps, +10 more.
lora_infoA
Full detail for one LoRA, including description, tags, past usage and a ready-to-paste prompt fragment with its trigger words.
Inputs: name (required).
lorasA
Search available LoRAs by name, title, tags, trigger words or description.
Only call this when the request actually calls for one (a named style,
character, or concept) — most generations need no LoRA at all. kind can be
"content" or "accelerator"; accelerators change the sampling regime rather
than the image, so adopting one means adjusting steps and CFG together.
Inputs: kind, limit, query, verbose, +1 more.
model_profileA
Describe the currently loaded checkpoint: architecture preset, whether it behaves as a turbo/distilled model, the sampling parameters that actually worked before, the expected prompt dialect, and whether its VAE and text encoder modules exist. Call before writing a prompt for an unfamiliar model.
Inputs: no named parameters.
modelsA
List or load checkpoints. action: "list" | "load" | "refresh".
Loading swaps the model for the whole instance, including any human using
the web UI at the same time, and takes several seconds — only do it when the
operator asked for that model. When the target belongs to a different
architecture, its preset, VAE and text encoder are switched with it, since
Forge would otherwise load it against whatever modules are selected now. The
architecture is inferred from two signals and only acted on when they agree;
pass preset to state it outright.
Inputs: name, limit, query, action, +1 more.
module_checkA
Check the VAE and text encoders loaded for an architecture against what it actually needs, and list installed files that could fill any gap.
Defaults to the active preset. Worth calling after switching architecture or when output looks wrong for no obvious reason: Forge records the last selection made under a preset, so loading a checkpoint while another preset was active can leave the wrong modules attached. Where the reference does not state a VAE, it says so instead of guessing — a wrong VAE degrades output without raising an error.
Inputs: preset.
module_downloadA
Find, and optionally fetch, a VAE or text encoder the architecture needs.
Called with no arguments it lists what the active preset is missing and
where each file comes from, downloading nothing. Downloading requires both a
label naming one entry and confirm=True, and the operator has to agree
first: these are multi-gigabyte files written into their models folder,
often across a network share.
Links come from the Forge Classic wiki's Download Models page. Where several builds exist — bf16, fp8_scaled, gguf — they are all offered, because which to take depends on the operator's hardware, not on a default worth hiding.
Inputs: label, preset, confirm.
progressB
Check or stop the current generation. action: "status" | "interrupt" | "skip".
Inputs: action.
prompt_dialectA
How the loaded checkpoint expects to be prompted, with its quality tags.
Returns the dialect (pony / illustrious / animagine / anima / sd15 / sdxl_base / natural), the quality prefix and negative baseline it needs, and where that conclusion came from. Quality tags are not decoration: an Illustrious prompt without them degrades, and a Flux prompt with them degrades too.
When the dialect comes back unknown — xl covers Pony, Illustrious and
stock SDXL, which share tensors and preset — ask the operator, then call
again with confirm set to their answer. It is cached by file hash and
never asked again.
Inputs: confirm.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Tools are mostly distinct by resource and action—LoRA search vs detail, module check vs download, generation vs progress—but model_profile and prompt_dialect overlap on prompt dialect, and models/model_profile could be confused at a glance. The detailed descriptions mitigate most ambiguity.
Names consistently use lowercase snake_case and a readable resource-oriented style (loras, lora_info, models, module_check). Not all are verb_noun—generate is a bare verb and progress is ambiguous—so it is not a perfect 5, but there is no chaotic convention mixing.
Ten tools is well within the ideal 3–15 range and matches the server's scope: discovery, model/prompt/LoRA/module setup, generation, and progress control. No tool feels redundant or superfluous.
The surface covers the full generation workflow—model loading, profiling, prompt dialect, LoRA lookup, module diagnostics/download, generate, and progress monitoring. Minor gaps exist (no LoRA download/management, no explicit output/history listing), but they are not required for the core purpose.
Maintenance
Related MCP Connectors
Search bilingual image prompts, upload reference images, and generate and download images from your AI agent. OAuth sign-in; image generation uses paid subscription credits. Setup: https://framepond.com/en/agent?utm_source=agent_directory&utm_campaign=agent_launch
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Remote MCP for RunComfy: ComfyUI deployments, hosted models, LoRA training. 31 tools.
Generate AI images, video, music, and sound effects, and upscale them, from any MCP client.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI coding agents to control a local InvokeAI creative engine, supporting text-to-image, image-to-image, masked inpaint, upscaling, and full queue, model, gallery, board, and workflow management.132MIT
- AlicenseAqualityCmaintenanceEnables AI agents to interact with a Stable Diffusion REST API for image generation, inpainting, model management, and merging.18GPL 3.0
- AlicenseAqualityBmaintenanceExposes a local Forge or AUTOMATIC1111 SDXL backend as typed image-generation tools, enabling any MCP client to generate and edit images through a deterministic, stateless interface with server-enforced SFW content.3Mozilla Public 2.0
- AlicenseBqualityCmaintenanceEnables Claude Code to call local generative AI services on a LAN, letting users list and chat with Ollama models and list checkpoints, LoRAs, and samplers or generate and save images via Stable Diffusion WebUI Forge Neo. Requests can be made in natural language, with per-call options for model, image size, and Hires.fix settings.1MIT