awkoy/replicate-flux-mcp

Replicate Flux MCP는 AI 어시스턴트가 고품질 이미지와 벡터 그래픽을 생성할 수 있도록 지원하는 고급 Model Context Protocol (MCP) 서버입니다. Replicate API를 통해 래스터 이미지(raster images)를 위한 Black Forest Labs의 Flux Schnell 모델과 벡터 그래픽을 위한 Recraft의 V3 SVG 모델을 활용합니다.

• 시작하기 및 통합 (Getting Started & Integration)

• 기능 (Features)

• 문서 (Documentation)

• 개발 (Development)

• 기술적 세부 사항 (Technical Details)

• 문제 해결 (Troubleshooting)

• 기여하기 (Contributing)

• 라이선스 (License)

• 리소스 (Resources)

• 예시 (Examples)

Replicate API 토큰 확보하기- Replicate에서 가입하세요

• 계정 설정에서 API 토큰을 생성하세요

통합 방법 선택하기- 선호하는 MCP 클라이언트에 따라 아래의 통합 옵션 중 하나를 따르세요

AI 어시스턴트에게 이미지 생성 요청하기- 자연스럽게 요청하세요: "해질녘의 평온한 산 풍경 이미지를 생성해 줄 수 있나요?"

• 또는 더 구체적으로 요청하세요: "전경에 노을빛을 반사하는 호수가 있는 평화로운 산 장면 이미지를 만들어 주세요"

고급 기능 탐색하기- 맞춤형 결과를 위해 다양한 파라미터(parameter) 설정을 시도해 보세요

• generate_svg를 사용하여 SVG 생성을 실험해 보세요

• 배치 이미지 생성(batch image generation) 또는 변형 생성(variant generation) 기능을 사용하세요

• 프로젝트 디렉토리에서 .cursor/mcp.json 파일을 생성하거나 편집하세요:

{
"mcpServers": {
"replicate-flux-mcp": {
...

• YOUR_TOKEN을 실제 Replicate API 토큰으로 교체하세요 - 변경 사항을 적용하려면 Cursor를 재시작하세요

• Cursor를 열고 설정(Settings)으로 이동하세요

• "MCP" 또는 "Model Context Protocol" 섹션으로 이동하세요

• "Add Server" 또는 그에 상응하는 버튼을 클릭하세요

• 적절한 필드에 다음 명령어를 입력하세요:

env REPLICATE_API_TOKEN=YOUR_TOKEN npx -y replicate-flux-mcp

• YOUR_TOKEN을 실제 Replicate API 토큰으로 교체하세요 - 설정을 저장하고 필요한 경우 Cursor를 재시작하세요

• 구성 디렉토리에서 mcp.json 파일을 생성하거나 편집하세요:

{
"mcpServers": {
"replicate-flux-mcp": {
...

• YOUR_TOKEN을 실제 Replicate API 토큰으로 교체하세요 - 변경 사항을 적용하려면 Claude Desktop을 재시작하세요

이 MCP 서버는 Smithery에서 호스팅 서비스로 제공되므로, 직접 서버를 구축하지 않고도 사용할 수 있습니다.

• Smithery를 방문하여 계정이 없다면 생성하세요
• Replicate Flux MCP 서버 페이지로 이동하세요
• "Add to Workspace"를 클릭하여 서버를 Smithery 워크스페이스에 추가하세요
• MCP 클라이언트(Cursor, Claude Desktop 등)가 Smithery 워크스페이스 URL을 사용하도록 설정하세요

MCP 클라이언트와 함께 Smithery를 사용하는 방법에 대한 자세한 정보는 Smithery 문서를 참조하세요.

이 MCP 서버는 Glama.ai에서도 호스팅 서비스로 제공되어, 로컬 설정 없이 사용할 수 있는 또 다른 옵션을 제공합니다.

• Glama.ai를 방문하여 계정이 없다면 생성하세요
• Replicate Flux MCP 서버 페이지로 이동하세요
• "Install Server"를 클릭하여 서버를 워크스페이스에 추가하세요
• MCP 클라이언트가 Glama.ai 워크스페이스를 사용하도록 설정하세요

자세한 내용은 Glama.ai MCP 서버 문서를 참조하세요.

🖼️ 고품질 이미지 생성— 종횡비(aspect ratio), 메가픽셀(megapixels), 추론 단계(inference steps), 출력 형식(output format) 및 시드(seed)를 완전히 제어할 수 있는 Flux Schnell 래스터(raster) 이미지.
🎨 벡터 그래픽— 로고, 아이콘 및 다이어그램을 위한 Recraft V3 SVG.
📊 배치 + 변형 (Batch + Variants)— N개의 프롬프트로부터 N개의 이미지를 생성하거나, 하나의 프롬프트로부터 N개의 변형(시드 기반 또는 프롬프트 수정자 기반)을 생성합니다.
🧩 임의의 Replicate 모델— run_replicate_model 탈출구(escape hatch)는 owner/name[:version] 형태의 모든 참조를 허용하며, OpenAPI 입력 스키마를 위한 get_model_schema 내성(introspection)을 제공합니다. REPLICATE_MODEL_ALLOWLIST를 통해 선택적 화이트리스트 설정이 가능합니다.
📦 구조화된 출력 (Structured Output)— 모든 generate_* 도구는 각 도구별 outputSchema(URL, 프롬프트, 형식, 종횡비, 변형별 시드 등)에 맞춰 사람이 읽을 수 있는 콘텐츠와 함께 기계가 읽을 수 있는 structuredContent를 반환합니다.
⏳ 진행 상황 알림 (Progress Notifications)— 배치 및 변형 생성 시 progressToken을 통해 옵트인(opt-in)한 클라이언트에 notifications/progress를 전송하므로, 실행 시간이 긴 작업이 블랙박스 상태로 방치되지 않습니다.
💬 큐레이션된 프롬프트— 5개의 준비된 프롬프트 템플릿 (logo, portrait, svg-icon, product-shot 등)

, isometric-diagram)

이 기능들은 Claude Desktop의 슬래시 팔레트(/) 및 Cursor의 @ 메뉴에 나타납니다.

🏷️ 적절한 도구 주석 (Tool Annotations)— readOnlyHint, destructiveHint, openWorldHint, idempotentHint를 올바르게 설정하여 클라이언트가 안전성과 비용을 판단할 수 있도록 합니다.

🪵 구조화된 로깅 (Structured Logging)— 서버 측 오류가 stderr 대신 notifications/message를 통해 전달됩니다.

🔌 범용 MCP 호환성 (Universal MCP Compatibility)— MCP 프로토콜 2025-11-25를 준수하며, Claude Desktop, Cursor, Cline, Zed 및 모든 규격 준수 클라이언트와 작동합니다.

🔍 생성 이력 (Generation History)— imagelist, svglist, predictionlist 리소스를 통해 과거 실행 내역을 탐색할 수 있습니다.

Flux Schnell 모델을 사용하여 텍스트 프롬프트 기반의 이미지를 생성합니다.

{
  prompt: string; // 필수: 생성할 이미지에 대한 텍스트 설명
  seed?: number; // 선택 사항: 재현 가능한 생성을 위한 랜덤 시드(seed)
  ...
}

Flux Schnell 모델을 사용하여 프롬프트 배열을 기반으로 여러 이미지를 생성합니다.

{
  prompts: string[]; // 필수: 생성할 이미지들에 대한 텍스트 설명 배열 (1-10개 프롬프트)
  seed?: number; // 선택 사항: 재현 가능한 생성을 위한 랜덤 시드(seed)
  ...
}

단일 프롬프트로부터 동일한 이미지의 여러 변형(variants)을 생성합니다.

{
  prompt: string; // 필수: 변형을 생성할 대상 이미지에 대한 텍스트 설명
  num_variants: number; // 필수: 생성할 이미지 변형 수 (2-10, 기본값: 4)
  ...
}

Recraft V3 SVG 모델을 사용하여 텍스트 프롬프트 기반의 SVG 벡터 이미지를 생성합니다.

{
  prompt: string; // 필수: 생성할 SVG에 대한 텍스트 설명
  size?: string; // 선택 사항: 생성된 SVG의 크기 (기본값: "1024x1024")
  ...
}

Replicate에서 최근 예측(predictions) 목록을 가져옵니다.

{
  limit?: number; // 선택 사항: 반환할 최대 예측 수 (1-100) (기본값: 50)
}

특정 예측에 대한 상세 정보를 가져옵니다.

{
  predictionId: string; // 필수: 가져올 예측의 ID
}

owner/name[:version] 형식을 사용하여 Replicate에 호스팅된 모든 모델을 실행합니다.

참조하십시오. 큐레이션된 도구 중 적합한 것이 없을 때 이를 탈출구(escape hatch)로 사용하십시오. 입력 형태(input shape)를 모른다면 먼저 get_model_schema를 호출하십시오.

{
model: string; // 필수: 'owner/name' 또는 'owner/name:version'
input: Record<string, unknown>; // 필수: 모델 입력 파라미터 (Model input parameters)
...

호출할 수 있는 모델을 제한하려면 REPLICATE_MODEL_ALLOWLIST 환경 변수(쉼표로 구분된 owner/name 항목)를 설정하십시오. 설정하지 않으면 모든 모델이 허용됩니다. 설정하되 비워두면 모든 모델이 거부됩니다 (서버가 모든 것을 조용히 허용하기보다 차단된 상태로 실패하도록 설계되었습니다).

run_replicate_model에 올바른 파라미터를 전달할 수 있도록 Replicate 모델의 OpenAPI 입력 스키마(input schema)와 설명을 가져옵니다.

{
model: string; // 필수: 'owner/name' 형식의 Replicate 모델 참조
}

Flux Schnell 모델로 생성된 이미지 생성 이력을 탐색합니다.

Recraft V3 SVG 모델로 생성된 SVG 이미지 생성 이력을 탐색합니다.

모든 Replicate 예측(predictions) 이력을 탐색합니다.

Claude Desktop의 슬래시 메뉴(/)와 Cursor의 @ 팔레트에 나타나는 큐레이션된 템플릿입니다. 각 템플릿은 합리적인 기본값(defaults)을 채운 뒤 관련 생성 도구로 작업을 위임합니다.

프롬프트 (Prompt)	설명 (Description)	인자 (Arguments)
logo	브랜드/제품 로고	brand, style?, palette?
portrait	실사 초상화	subject, mood?, lens?
svg-icon	단일 개념 벡터 아이콘	concept, style?
product-shot	스튜디오 제품 사진	product, surface?
isometric-diagram	아이소메트릭 기술 일러스트레이션	subject, emphasis?

모든 generate_* 도구는 사람이 읽을 수 있는 content (텍스트 + 이미지 블록)와 도구의 outputSchema와 일치하는 기계가 읽을 수 있는 structuredContent를 모두 반환합니다.

도구	structuredContent 형태
generate_image	{ url, prompt, format, aspect_ratio, seed? }
generate_svg	{ url, prompt, size, style, svg? }
generate_multiple_images	{ images: [{ url, prompt }], format, aspect_ratio }
generate_image_variants	{ base_prompt, variation_mode, variants: [{ variant_index, url, prompt_used, seed? }], format, aspect_ratio }

MCP 구조화된 출력(structured output)을 이해하는 클라이언트는 산문(prose)을 구문 분석할 필요 없이 URL과 메타데이터를 직접 소비할 수 있습니다.

변수	필수 여부	용도
REPLICATE_API_TOKEN	예	Replicate용 API 토큰입니다. 누락된 경우 서버가 즉시 종료됩니다.
REPLICATE_MODEL_ALLOWLIST	아니오	run_replicate_model을 제한하는 쉼표로 구분된 owner/name 항목입니다. 설정하지 않으면 모든 모델이 허용됩니다. 빈 값으로 설정하면 모두 거부(fail-closed)됩니다. 이 값은 프로세스 시작 시 한 번 평가되므로, MCP 클라이언트의 env 블록에 설정해야 합니다 (나중에 dotenv로 로드하는 방식으로는 안 됩니다).

• 저장소 복제:

git clone https://github.com/awkoy/replicate-flux-mcp.git
cd replicate-flux-mcp

• 의존성 설치:

npm install

• TypeScript 워처 시작:

npm run watch

• 프로젝트 빌드:

npm run build

• MCP Inspector를 사용하여 서버 스모크 테스트:

npm run inspector

• 클라이언트에 연결:

{
"mcpServers": {
"image-generation-mcp": {
...

이 프로젝트는 현재 자동화된 테스트 스위트가 없습니다. 검증은 다음을 통해 수행됩니다:

npm run build
— TypeScript 타입 체크가 대부분의 회귀(regression)를 포착합니다.
npm run inspector
— 빌드된 바이너리를 공식 MCP Inspector를 통해 도구, 리소스 및 프롬프트에 대한 엔드투엔드 스모크 테스트를 수행합니다.

적절한 테스트 프레임워크(예: Vitest + MCP stdio 클라이언트 하네스)를 추가하는 기여는 환영합니다.

Model Context Protocol SDK - 도구 및 리소스 관리를 위한 핵심 MCP 기능
Replicate API - 최첨단 AI 이미지 생성 모델에 대한 액세스 제공
TypeScript - 타입 안정성 (Type safety)을 보장하고 현대적인 JavaScript 기능 활용
Zod - 견고한 API 상호작용을 위한 런타임 타입 검증 (Runtime type validation) 구현

서버는 src/config/index.ts에 있는 CONFIG 객체를 수정하여 구성할 수 있습니다:

export const CONFIG = {
serverName: "replicate-flux-mcp",
serverVersion: "0.4.0",
...

modelAllowlist는 프로세스 시작 시 REPLICATE_MODEL_ALLOWLIST로부터 한 번 평가됩니다. 이를 변경한 후에는 서버를 재시작하십시오.

• 환경 변수에 REPLICATE_API_TOKEN이 올바르게 설정되었는지 확인하십시오.

• Replicate API를 직접 테스트하여 토큰이 유효한지 확인하십시오.

• 모델에는 특정 프롬프트를 차단할 수 있는 내장된 안전 필터 (Safety filter)가 있습니다.

• 잠재적으로 문제가 될 수 있는 콘텐츠를 피하기 위해 프롬프트를 수정해 보십시오.

• 더 큰 이미지나 사용량이 많은 서버의 경우, 설정에서 pollingAttempts 또는 pollingInterval을 늘려야 할 수도 있습니다.

• 기본 설정은 대부분의 사용 사례에서 작동해야 합니다.

기여는 언제나 환영합니다! 기여하려면 다음 단계를 따르십시오:

• 저장소(Repository)를 포크(Fork)합니다.
• 기능 브랜치를 생성합니다 (git checkout -b feature/amazing-feature).
• 변경 사항을 커밋합니다 (git commit -m 'Add some amazing feature').
• 브랜치에 푸시합니다 (git push origin feature/amazing-feature).
• 풀 리퀘스트(Pull Request)를 생성합니다.

기능 요청이나 버그 보고는 GitHub 이슈(Issue)를 생성해 주세요. 이 프로젝트가 마음에 드신다면 저장소에 스타(Star)를 눌러주세요!

이 프로젝트는 MIT 라이선스(MIT License) 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하십시오.

• Model Context Protocol 문서
• Replicate API 문서
• Flux Schnell 모델
• Recraft V3 SVG 모델
• MCP TypeScript SDK
• Smithery 문서
• Glama.ai MCP 서버들

다중 프롬프트	프롬프트 변형

다음은 도구를 사용하는 몇 가지 예시입니다:

서로 다른 프롬프트를 사용하여 한 번에 여러 개의 서로 다른 이미지를 생성합니다:

{
"prompts": [
"A red sports car on a mountain road",
...

시드 (seeds)를 사용하여 동일한 개념에 대한 다양한 해석을 생성합니다:

{
"prompt": "A futuristic city skyline at night",
"num_variants": 4,
...

또는 프롬프트 수정자 (prompt modifiers)를 사용하여 스타일 변형을 탐색합니다:

{
"prompt": "A character portrait",
"prompt_variations": [
...

Yaroslav Boiko가 ❤️를 담아 만들었습니다.