🌉 Forge Neo MCP

Stable Diffusion WebUI Forge - Neo용 MCP 서버 · MCP를 지원하는 모든 AI 에이전트에서, 자신의 GPU로 이미지를 생성하세요

Claude — 또는 MCP를 지원하는 모든 에이전트 — 에게 이미지를 요청하면, 로컬 Forge Neo에서 생성합니다. 어떤 체크포인트가 로드되어 있는지 읽고, 해당 모델이 기대하는 샘플링 파라미터와 프롬프트 스타일을 파악한 뒤, 프롬프트를 작성하고 파일을 돌려줍니다.

원하지 않는 한 단계 수(CFG)나 샘플러를 직접 지정할 필요가 없습니다. 이 모든 것은 사용자 자신의 설정에서 비롯됩니다: 인스턴스의 설정, 과거 생성 기록, 체크포인트의 메타데이터. 결정할 수 없는 부분이 있으면 추측하지 않고 물어봅니다.

[!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가 127.0.0.1:7860에 있지 않을 때만 필요합니다.

모든 것이 한 머신에 있는 경우

할 일이 없습니다 — 기본값으로 충분합니다.

Forge가 다른 머신에 있는 경우

Forge를 --listen --api로 시작한 다음, 브리지를 해당 주소로 지정하고 경로를 매핑하세요:

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 목록이 비어 있는 것입니다. UI에서 새로고침하세요.

💬 사용 방법

그냥 요청하세요. 에이전트가 나머지를 처리합니다.

"겨울 하이킹에 관한 포스트의 커버 이미지"

로드된 모델을 확인하고, 해당 모델이 산문형 프롬프트를 원하는지 태그형을 원하는지 파악한 후, 그에 맞게 프롬프트를 작성하고 생성합니다.

"같은 걸 내가 썸네일에 쓰는 스타일로"

LoRA를 검색하여 원하는 것을 찾고, 트리거 단어와 평소 사용하는 가중치를 가져와 프롬프트에 작성합니다 — 눈에 보이게, 전송된 내용을 읽을 수 있도록.

"내 인물 사진 모델로 전환해줘"

해당 체크포인트를 로드합니다. 다른 아키텍처에 속한다면, 일치하는 VAE와 텍스트 인코더도 함께 로드됩니다.

직접 물어볼 가치가 있는 다른 것들:

• "어떤 모델이 로드되어 있고 어떻게 프롬프트해야 하나요?" — 프로필을 평이한 용어로

• "내 LoRA 중 이 체크포인트와 호환되는 것은?" — 호환 가능한 것만 필터링

• "내 flux 설정이 완전한가요?" — VAE와 텍스트 인코더 확인

• "중지" — 실행 중인 생성 중단

🛠️ 도구

에이전트가 스스로 선택합니다. 여기 목록은 어떤 작업이 가능한지 알려드리기 위한 것입니다.

🔧 문제 해결

Forge에 연결할 수 없다고 표시됨 Forge가 --api로 실행 중이고 http://127.0.0.1:7860/docs에 /sdapi/v1/ 엔드포인트가 있는지 확인하세요. Forge가 다른 머신에 있다면 --listen도 필요하며, 방화벽이 차단하고 있을 수 있습니다.

결과가 base64로 반환되어 대화가 넘쳐남 FORGE_PATH_MAP이 없거나 일치하지 않습니다. Forge가 보고하는 경로 — 모든 생성물의 정보에서 확인 가능 — 와 같은 폴더에 접근할 때 사용하는 경로를 비교하세요.

평소 설정을 인식하지 못함 과거 이미지에서 학습하는데, 이를 위해서는 Forge가 생성 파라미터를 저장해야 합니다. Settings → Saving images에서 **"Save text information about generation parameters as chunks to png files"**를 활성화하거나 .txt 사이드카를 켜세요. 둘 다 없으면 출력물에 파라미터가 포함되지 않아 아키텍처 기본값으로 대체됩니다.

SDXL 체크포인트의 계열을 계속 물어봄 Pony, Illustrious, Animagine, 기본 SDXL은 파일만으로 구분할 수 없습니다 — 같은 텐서, 같은 프리셋, 다른 프롬프트 어휘. 한 번 답하면 파일별로 기억되어 다시 묻지 않습니다.

아키텍처 전환 후 이미지가 이상하게 보임 모듈 검사를 요청하세요. Forge는 각 프리셋에서 마지막으로 선택한 VAE와 텍스트 인코더를 기억하므로, 다른 프리셋이 활성화된 상태에서 체크포인트를 로드하면 잘못된 모듈이 연결될 수 있습니다. 검사는 무엇이 누락되었는지, 올바른 파일이 이미 설치되어 있는지 알려줍니다.

공간 부족으로 다운로드가 거부됨 의도된 동작입니다 — 시작 전에 여유 공간을 확인하여 수 기가바이트를 다운로드하는 중에 실패하지 않도록 합니다. 공간을 확보하거나 bf16 대신 fp8_scaled 같은 더 가벼운 빌드를 선택하세요.

🎯 제공 기능

• 모델에 맞는 샘플링 파라미터. 가능한 경우 사용자의 과거 생성 기록에서, 그렇지 않으면 인스턴스 설정에서 가져옵니다 — 이 저장소의 표에서 가져오는 것이 아닙니다.

• 올바른 프롬프트 어휘. 도움이 되는 곳에는 품질 태그, 해가 되는 곳에는 없음: 캡션으로 학습된 모델에 masterpiece, best quality를 추가하면 프롬프트가 개선되는 대신 희석됩니다.

• 검색 가능한 LoRA. 이름, 태그, 트리거 단어 또는 설명으로, 실제 사용하는 가중치와 함께. 프롬프트에 추가되는 것은 항상 표시됩니다.

• 정직한 불확실성. 증거가 부족하면 그렇게 말하고 물어봅니다. 조용한 추측은 없습니다.

• 모듈 상태 검사. 프리셋이 잘못된 VAE나 텍스트 인코더를 선택했을 때 감지하고, 누락된 항목의 공식 다운로드 위치를 알려줍니다.

각 답변이 어떻게 도출되는지에 대한 설명은 해당 코드 옆의 소스에 있습니다.

🗺️ 로드맵

• 비디오 (Wan) — Forge는 4n+1 배수의 프레임 수로 비디오를 생성하고 ffmpeg로 인코딩하지만, API는 결과 경로를 버립니다. 디스크에서 수집하는 것은 이미 이미지가 반환되는 방식이므로, 대부분 배관 작업입니다.

• EXIF 메타데이터 — JPEG와 WebP는 .txt 사이드카가 꺼져 있을 때 EXIF에 파라미터를 저장합니다. 현재 이 조합은 기록을 생성하지 않습니다.

• 인증 — FORGE_AUTH는 구현되었지만 실제 --api-auth 인스턴스에서 테스트되지 않았습니다.

📄 크레딧

• Forge Neo — Haoming02 제작 — 브리지가 연결하는 WebUI, 그리고 모듈 참조의 기반이 되는 Download Models 위키

• 모델 카드에 실제 프롬프팅 가이드를 게시한 모델 작성자들 — 방언 테이블은 추측이 아닌 이 자료들로 구축되었습니다

• Model Context Protocol — 프로토콜 및 Python SDK

• CivitAI — 선택적 조회에 사용되는 공개 해시 기반 엔드포인트

📜 라이선스

MIT — LICENSE 참조

Stable Diffusion 커뮤니티를 위해 ❤️로 제작

버그 신고 • 기능 요청 • 토론 • ☕ Ko-fi