Skip to main content
Glama

🌉 Forge Neo MCP

Forge Neo MCP Python Version License

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.

IMPORTANT

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 --api

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=--api

Keep 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-mcp

3 · Register it with your agent

Claude Code

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

Claude 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

FORGE_URL

Where Forge is

http://127.0.0.1:7860

FORGE_AUTH

user:password, if you started Forge with --api-auth

none

FORGE_PATH_MAP

Translates Forge's paths into ones your machine can reach

none

FORGE_OUTPUT_DIR

Your output folder, if it cannot be found automatically

auto

FORGE_TIMEOUT

Seconds to wait on a request

600

FORGE_HISTORY_LIMIT

How many recent images to read when learning your settings

600

FORGE_CIVITAI_LOOKUP

1 allows identifying a checkpoint by hash online

off

FORGENEO_CACHE_DIR

Where your confirmed answers are remembered

~/.forgeneo-mcp

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-mcp

FORGE_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.

NOTE

--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 read

Three things worth a glance:

  • filesystem: base64 — FORGE_PATH_MAP is 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: 0 with 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

capabilities

What this instance offers and what the bridge could read

model_profile

The loaded checkpoint: parameters, prompt style, module health

prompt_dialect

How this model expects to be prompted, with its quality tags

loras

Search your LoRAs by name, tag, trigger word or description

lora_info

Everything about one LoRA, with a ready prompt fragment

models

List, load or refresh checkpoints

module_check

Whether the loaded VAE and text encoders suit the architecture

module_download

Where a missing module comes from — fetches only if you approve

generate

Generate from a written prompt, txt2img or img2img

progress

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 quality to 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+1 and 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 .txt sidecar is off; that combination currently yields no history.

  • Authentication — FORGE_AUTH is implemented but has not been exercised against a live --api-auth instance.


📄 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 tools
capabilitiesA

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

    A3.9/5.0

    Scored across 10 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      13
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Exposes 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.
      3
      Mozilla Public 2.0
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      1
      MIT