sdnext-mcp

SD.Next(Stable Diffusion Next) WebUI용 MCP(Model Context Protocol) 서버입니다.

SD.Next의 REST API(/sdapi/v1/* + /sdapi/v2/civitai/*)를 125개의 MCP 도구로 감싸서, LLM 호스트(Claude Desktop, DSH 등)가 텍스트-이미지 생성, 이미지-이미지 변환, 제어된 생성, 업스케일링, 디테일러, LoRA, 스크립트, 캡셔닝/태깅/VQA, 모델 및 옵션 관리, 서버 내부 조회, 파일/갤러리, CivitAI 등 SD.Next의 모든 사용 시나리오를 구동할 수 있게 합니다.

이것은 얇은 HTTP 클라이언트입니다. Python을 내장하지 않으며 WebUI를 실행하지 않습니다. --api --listen으로 SD.Next를 직접 실행해야 합니다. MCP 서버는 HTTP를 통해 SD.Next와 통신할 뿐입니다.

이것이 존재하는 핵심 이유: SD.Next의 요청 매개변수는 A1111과 다릅니다(모듈식 가이던스, 1024 기본 캔버스, 내장 YOLO 디테일러, 별도 축으로서의 스케줄러, UNet/DiT 등). 따라서 A1111용 MCP 코드는 SD.Next에서 작동하지 않습니다. 여기의 모든 도구는 SD.Next의 실제 pydantic 요청 필드를 기반으로 모델링되었습니다.

설치

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

Related MCP server: sd-neo-mcp

실행

기본값은 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

이미지는 data: 접두어 없이 raw base64 PNG로 주고받습니다. 이미지 입력이 필요한 곳에서는 "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/(도메인별 파일 하나씩).