sdnext-mcp

面向 SD.Next（Stable Diffusion Next）WebUI 的 Model Context Protocol (MCP) 服务器。

它将 SD.Next 的 REST API（/sdapi/v1/* + /sdapi/v2/civitai/*）封装为 125 个 MCP 工具，使 LLM 宿主（Claude Desktop、DSH 等）能够驱动 SD.Next 的每一个使用场景：文生图、图生图、控制引导生成、放大、detailer、LoRA、脚本、字幕/打标/VQA、模型与选项管理、服务器自省、文件/图库以及 CivitAI。

这是一个轻量 HTTP 客户端。 它不内嵌 Python，也不启动 WebUI。你必须自行以 --api --listen 运行 SD.Next；MCP 服务器只是通过 HTTP 与它通信。

它存在的核心原因：SD.Next 的请求参数与 A1111 不同（模块化引导、1024 默认画布、内置 YOLO detailer、调度器作为独立维度、UNet/DiT 等），因此 A1111 的 MCP 代码无法用于它。这里的每个工具都基于 SD.Next 实际的 pydantic 请求字段建模。

要求

• Node.js ≥ 18（使用全局 fetch、FormData、AbortSignal.timeout）

• 一个以 --api --listen 启动的、正在运行的 SD.Next 实例（添加 --api-auth user:pass 以启用认证）

Related MCP server: sd-neo-mcp

安装

cd sdnext_mcp
npm install          # installs @modelcontextprotocol/sdk + zod

运行

默认使用 stdio 传输（由你的 MCP 宿主启动）：

# in your MCP host config
{
  "mcpServers": {
    "sdnext": {
      "command": "node",
      "args": ["/abs/path/to/sdnext_mcp/src/index.js"],
      "env": {
        "SDNEXT_BASE_URL": "http://127.0.0.1:7860",
        "SDNEXT_USERNAME": "user",
        "SDNEXT_PASSWORD": "pass"
      }
    }
  }
}

或者直接运行 Streamable HTTP 传输：

SDNEXT_MCP_TRANSPORT=http SDNEXT_MCP_PORT=8787 node src/index.js
# → http://127.0.0.1:8787/mcp

配置（环境变量）

工具族（共 125 个）

• 生成 — sdnext_txt2img、sdnext_img2img、sdnext_control、sdnext_process_image、sdnext_process_batch、sdnext_detail、sdnext_prompt_enhance

• 枚举器 — sdnext_list_samplers … sdnext_list_masking（29 个列表工具）

• 图像理解 — sdnext_caption、sdnext_caption_dispatch、sdnext_tagger、sdnext_vqa、sdnext_analyze

• 模型/选项 — 刷新/选择/加载 checkpoint、VAE、UNet、LoRA；sdnext_get_options/sdnext_set_options

• 服务器 — sdnext_status、sdnext_progress、中断/跳过、重启/关闭、日志、历史、存储、GPU

• 文件/图库 — sdnext_upload、sdnext_file、delete-、browser/、sdnext_png_info

• 控制处理 — sdnext_preprocess、sdnext_mask、sdnext_detect

• 审核 — sdnext_nudenet、sdnext_prompt_lang、sdnext_image_guard、sdnext_prompt_banned

• CivitAI — 搜索、模型/版本、下载队列、设置、书签、封禁、历史（27 个工具）

• 元 — sdnext_list_tools、sdnext_call_api（通用透传）、自动补全文件管理

在运行时执行 sdnext_list_tools 可查看完整目录，或运行 node scripts/dump_tools.mjs。

典型工作流

sdnext_list_checkpoints   → pick a model
sdnext_list_samplers      → pick a sampler
sdnext_txt2img { prompt, sd_model_checkpoint, sampler_name, width:1024, height:1024, steps:20 }
sdnext_progress           → poll while it runs
sdnext_caption / sdnext_tagger → understand a result

图像输入输出均为原始 base64 PNG（无 data: 前缀）；在图像作为输入的位置接受 "upload:<id>" 引用。在任何生成工具上传递 save_dir 也可将结果写入磁盘。

脚本

npm run check          # syntax-check the entry
node scripts/smoke.mjs # DRY_RUN stdio smoke test (no live server needed)
node scripts/dump_tools.mjs  # export the tool catalog

布局

架构文档请参阅 ../framework/（API 事实见 01-sdnext-api/，设计决策见 02-mcp-design/）。源码位于 src/ 下：config.js、client.js、image.js、registry.js、index.js 以及 tools/（每个领域一个文件）。