flux1-edit/README.md

FLUX.1 Edit MCP Server

FLUX.1 Kontext 모델을 이용한 이미지 편집 전용 MCP (Model Context Protocol) 서버입니다.

주요 기능

• 이미지 편집: FLUX.1 Kontext API를 이용한 고품질 이미지 편집
• 시드 기반 재현성: 동일한 시드로 일관된 편집 결과 보장
• 대용량 이미지 지원: 최대 20MB 이미지 처리
• MCP 통합: Claude와 완전 통합된 이미지 편집 도구

설치 및 설정

빠른 설치 (권장)

Windows 배치 파일 사용:

# 의존성 자동 설치
install_dependencies.bat

# 서버 실행
run.bat

PowerShell 스크립트 사용:

# 의존성 자동 설치
.\install_dependencies.ps1

# 서버 실행
.\run.ps1

수동 설치

1. Python 가상 환경 생성

python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

2. 의존성 설치

pip install -r requirements.txt

3. 환경변수 설정

copy .env.example .env  # Windows
cp .env.example .env    # Linux/Mac
# .env 파일에서 FLUX_API_KEY 설정

4. 필요한 디렉터리 생성

mkdir input_images generated_images temp

5. 서버 실행

python main.py

문제 해결

일반적인 오류들

"ModuleNotFoundError: No module named 'aiohttp'"

# 문제 진단
troubleshoot.bat

# 또는 직접 설치
pip install aiohttp==3.11.7

가상 환경 활성화 문제

# 가상 환경 재생성
rmdir /s venv
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

PowerShell 실행 정책 오류

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

문제 진단 도구

자동 진단 실행:

troubleshoot.bat

이 스크립트는 다음을 확인합니다:

• Python 설치
• pip 가용성
• 가상 환경 상태
• 필수 패키지 설치 상태
• 설정 파일 존재
• 로컬 모듈 import 가능성

수동 의존성 확인

python -c "
import aiohttp
import httpx  
import mcp
from PIL import Image
import dotenv
import pydantic
print('All dependencies are working!')
"

환경 요구사항

• Python 3.8 이상
• 안정적인 인터넷 연결 (FLUX API 통신용)
• FLUX API 키

사용 가능한 도구

flux_edit_image

FLUX.1 Kontext로 이미지를 편집합니다.

파라미터:

• input_image_b64: Base64 인코딩된 입력 이미지
• prompt: 편집 설명
• seed: 재현성을 위한 시드값
• aspect_ratio: "1:1" | "16:9" 등 (기본: "1:1")
• save_to_file: 파일 저장 여부 (기본: True)

validate_image

이미지 파일의 유효성을 검증합니다.

move_temp_to_output

임시 파일을 출력 디렉터리로 이동합니다.

디렉터리 구조

flux1-edit/
├── main.py                    # 메인 실행 파일
├── requirements.txt           # Python 의존성
├── .env                      # 환경 설정 (FLUX_API_KEY)
├── .env.example              # 환경 설정 예제
├── install_dependencies.bat  # Windows 자동 설치
├── install_dependencies.ps1  # PowerShell 자동 설치
├── run.bat                   # Windows 실행 스크립트
├── run.ps1                   # PowerShell 실행 스크립트
├── troubleshoot.bat          # 문제 진단 도구
├── src/                      # 소스 코드
│   ├── connector/            # FLUX API 연결
│   ├── server/               # MCP 서버
│   └── utils/                # 유틸리티
├── input_images/             # 입력 이미지
├── generated_images/         # 출력 이미지
├── temp/                     # 임시 파일
└── tests/                    # 테스트 파일

Claude 설정

MCP 서버를 Claude에 연결하려면:

1. Claude 설정에서 MCP 서버 추가
2. 서버 명령: python D:\Project\flux1-edit\main.py
3. 작업 디렉터리: D:\Project\flux1-edit

API 제한사항

• 최대 이미지 크기: 20MB
• 출력 형식: PNG 고정
• 결과 URL 유효시간: 10분
• 편집 타임아웃: 5분

로그 및 디버깅

• 로그 파일: flux1-edit.log
• 로그 레벨: INFO (콘솔), DEBUG (파일)
• 오류 추적: 전체 스택 트레이스 포함

지원 및 문의

문제가 지속되는 경우:

1. troubleshoot.bat 실행하여 진단 정보 확인
2. flux1-edit.log 파일에서 자세한 오류 로그 확인
3. 가상 환경 재생성 후 재시도

라이선스

MIT License