🌉 Forge Neo MCP

面向 Stable Diffusion WebUI Forge - Neo 的 MCP 服务器 · 让任何支持 MCP 的 AI 智能体在你的自有 GPU 上生成图像

向 Claude——或任何支持 MCP 的智能体——要一张图，它就会在你的本地 Forge Neo 上生成。它会读取当前加载的 checkpoint，推算出该模型期望的采样参数和提示词风格，写出提示词，然后把文件交给你。

除非你想，否则你完全不必指定步骤、CFG 或采样器。这些都来自你自己的配置：你实例的设置、你过去的生成记录、你 checkpoint 的元数据。凡是无法确定的地方，它会询问而不是猜测。

[!IMPORTANT] Forge Neo 必须以 --api 运行。不会向你的 Forge 目录安装任何东西——没有扩展，没有自定义节点。这座桥只与 Forge 已经暴露的 REST API 通信。

📋 目录

• 环境要求

• 安装

• 配置

• 首次运行

• 使用方法

• 工具

• 故障排查

• 它能为你做什么

• 路线图

• 致谢

Related MCP server: Nano Banana

✅ 环境要求

仅当 Forge 运行在另一台机器上时，才需要：能通过网络访问它，以及一个文件共享（如果你希望以文件路径而非 base64 形式获取结果）。

📦 安装

1 · 在 Forge Neo 中开启 API

编辑你的 webui-user.bat（Windows）或 webui-user.sh（Linux），添加 --api：

set COMMANDLINE_ARGS=--api

保留你已有的所有参数——只需追加 --api。重启 Forge。

验证是否成功： 打开 http://127.0.0.1:7860/docs。如果看到 /sdapi/v1/... 端点列表，说明 API 已开启。

2 · 安装桥接器

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

3 · 向你的智能体注册

Claude Code

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

Claude Desktop、Cursor 或任何带有 mcp.json 的客户端

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

重启你的客户端——MCP 服务器在启动时加载，因此工具会在新会话中出现。

⚙️ 配置

除 FORGE_URL 外一切都是可选的，而即使 FORGE_URL，也仅在 Forge 不在 127.0.0.1:7860 时才需要设置。

全部在同一台机器上

无需其他操作——默认配置即可覆盖。

Forge 在另一台机器上

以 --listen --api 启动 Forge，然后将桥接器指向它并映射其路径：

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 的读取方式为 Forge 的称呼 = 你的称呼。Forge 报告的路径形如 D:\forge-neo\output\...；如果你以 \\gpu-box\share\forge-neo\output\... 访问同一文件夹，该映射就能让桥接器把文件路径交给你，而不是几兆字节的 base64。

没有它一切也照常工作——只是你会收到 base64。

[!NOTE] --listen 会将 API 无密码地暴露到你的网络。如果这对你所在的环境有影响，请为 Forge 添加 --api-auth user:password，并将 FORGE_AUTH 设置为匹配值。

🚀 首次运行

打开一个新会话，让智能体检查连接。它会调用 capabilities 并报告发现：

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

有三件事值得留意：

• filesystem: base64 — FORGE_PATH_MAP 缺失或错误。不是致命问题，但结果会让你的对话变得臃肿。

• history: 0 — 它无法从你过去的工作中学习。通常是输出文件夹不可访问，或 Forge 未保存元数据（参见故障排查）。

• loras: 0 但已安装 LoRA — Forge 自身的 LoRA 列表为空；请在界面中刷新。

💬 使用方法

直接提出要求即可。其余由智能体处理。

"为一篇关于冬季徒步的文章生成封面图"

它会检查当前加载的模型，判断该模型偏好散文式还是标签式提示词，据此写出提示词并生成。

"同样的内容，但用我做缩略图时的风格"

它会搜索你的 LoRA，找到你指的那个，提取其触发词和你惯用的权重，并写入提示词——可见地写入，这样你能读到发送了什么。

"切换到我的肖像模型"

它会加载该 checkpoint。如果它属于不同的架构，匹配的 VAE 和文本编码器会一并加载。

其他值得直接询问的事项：

• "当前加载了什么模型，我应该如何给它写提示词？" — 用通俗语言描述模型档案

• "我的哪些 LoRA 与这个 checkpoint 兼容？" — 过滤出兼容的

• "我的 flux 配置完整吗？" — 检查 VAE 和文本编码器

• "停止" — 中断正在进行的生成

🛠️ 工具

你的智能体会自行选择使用这些工具；这里列出是为了让你知道它能做什么。

🔧 故障排查

提示无法连接到 Forge 确认 Forge 以 --api 运行，且 http://127.0.0.1:7860/docs 列出了 /sdapi/v1/ 端点。如果 Forge 在另一台机器上，它还需要 --listen，并且可能有防火墙阻挡。

结果以 base64 形式返回，淹没了对话 FORGE_PATH_MAP 缺失或不匹配。将 Forge 报告的路径——可在任何一次生成的信息中看到——与你访问同一文件夹所用的路径进行对比。

它不知道我惯用的设置 它从你过去的图像中学习，这需要 Forge 保存生成参数。在 设置 → 保存图像 中，保持 "将生成参数文本信息以 chunks 形式保存到 png 文件中" 为启用状态，或开启 .txt 伴生文件。两者都没有时，你的输出就不携带参数，它会回退到架构默认值。

它一直问我 SDXL checkpoint 属于哪个谱系 Pony、Illustrious、Animagine 和原版 SDXL 从文件本身无法区分——相同的张量、相同的预设、不同的提示词词汇。回答一次即可；它会按文件记住，之后不再询问。

切换架构后图像看起来不对 要求做一次模块检查。Forge 会记住每个预设下最后选择的 VAE 和文本编码器，因此在另一个预设处于活动状态时加载 checkpoint，可能会留下错误的模块。检查会指出缺失了什么，以及正确的文件是否已安装。

下载因空间不足被拒绝 这是有意为之——它会在开始前检查可用空间，而不是在下载了几 GB 之后才失败。腾出一些空间，或选择更轻量的构建，如 fp8_scaled 而非 bf16。

🎯 它能为你做什么

• 适配模型的采样参数。 优先取自你自己过去的生成记录，其次取自你实例的设置——而不是本仓库中的一张表。

• 正确的提示词词汇。 在有用处添加质量标签，在有害处不加：给一个基于描述训练的模型添加 masterpiece, best quality 会稀释提示词，而不是改善它。

• 你的 LoRA，可搜索。 按名称、标签、触发词或描述搜索，附带你实际使用的权重。任何内容在加入提示词之前都会展示给你。

• 诚实的未知。 证据不足时它会明说并询问。绝不默默猜测。

• 模块健康检查。 能注意到预设是否挂载了错误的 VAE 或文本编码器，并为缺失的模块指出官方下载地址。

每个答案的推导方式都记录在源码中，紧挨着推导它的代码。

🗺️ 路线图

• 视频（Wan） — Forge 通过 4n+1 倍数的帧数生成视频并用 ffmpeg 编码，但 API 会丢弃生成的路径。从磁盘收集已经是图像返回的方式，所以这主要是管道工作。

• EXIF 元数据 — 当 .txt 伴生文件关闭时，JPEG 和 WebP 会将参数存储在 EXIF 中；这种组合目前无法产生历史记录。

• 身份验证 — FORGE_AUTH 已实现，但尚未针对真实的 --api-auth 实例进行验证。

📄 致谢

• Forge Neo 作者 Haoming02 — 本桥接器所连接的 WebUI，以及模块参考所依据的 Download Models 维基

• 在模型卡片上发布真实提示词指导的模型作者 — 方言表正是基于这些内容构建的，而非凭空猜测

• Model Context Protocol — 协议和 Python SDK

• CivitAI — 可选查找功能使用的公开按哈希查询端点

📜 许可证

MIT — 参见 LICENSE

为 Stable Diffusion 社区用心制作 ❤️

报告 Bug • 请求功能 • 讨论 • ☕ Ko-fi