openai-gpt-image-mcp

OpenAI의 GPT-4o/gpt-image-1 이미지 생성 및 편집 API를 위한 모델 컨텍스트 프로토콜(MCP) 도구 서버입니다.

• OpenAI의 최신 모델을 사용하여 텍스트 프롬프트에서 이미지를 생성합니다 .

• 고급 프롬프트 제어를 사용하여 이미지를 편집 (인페인팅, 아웃페인팅, 합성)합니다.

• 지원 대상 : Claude Desktop, Cursor, VSCode, Windsurf 및 모든 MCP 호환 클라이언트.

✨ 특징

• create-image : 고급 옵션(크기, 품질, 배경 등)을 사용하여 프롬프트에서 이미지를 생성합니다.

• edit-image : 프롬프트와 선택적 마스크를 사용하여 이미지를 편집하거나 확장하며 파일 경로와 base64 입력을 모두 지원합니다.

• 파일 출력 : 생성된 이미지를 디스크에 직접 저장하거나 base64로 수신합니다.

🚀 설치

지엑스피1

🔑 구성

Claude Desktop 또는 VSCode(Cursor/Windsurf 포함) 구성에 추가:

⚡ 고급

• create-image 의 경우 n 설정하면 최대 10개의 이미지를 한 번에 생성할 수 있습니다.

• edit-image 의 경우, 편집 내용을 적용할 위치를 제어하기 위해 마스크 이미지(파일 경로 또는 base64)를 제공합니다.

• 모든 옵션은 src/index.ts 참조하세요.

🧑‍💻 개발

• TypeScript 소스: src/index.ts

• 빌드: yarn build

• 실행: node dist/index.js

📝 라이센스

MIT

🩺 문제 해결

• OPENAI_API_KEY 가 유효하고 이미지 API 액세스 권한이 있는지 확인하세요.

• 인증된 OpenAI 조직이 있어야 합니다. 인증 후 이미지 API 액세스가 활성화되기까지 15~20분이 소요될 수 있습니다.

• 파일 경로는 절대 경로여야 합니다.

• 파일 출력의 경우 디렉토리가 쓰기 가능한지 확인하세요.

• 파일 형식에 대한 오류가 표시되면 이미지 파일 확장자와 형식을 확인하세요.

⚠️ 제한 사항 및 대용량 파일 처리

• 1MB 페이로드 제한: MCP 클라이언트(Claude Desktop 포함)는 도구 응답에 대해 1MB의 제한을 두고 있습니다. 큰 이미지(특히 고해상도 또는 여러 이미지)를 base64로 반환하는 경우 이 제한을 쉽게 초과할 수 있습니다.

• 파일 출력으로 자동 전환: 전체 이미지 크기가 1MB를 초과하면 도구가 자동으로 이미지를 디스크에 저장하고 base64 대신 파일 경로를 반환합니다. 이를 통해 호환성을 보장하고 result exceeds maximum length of 1048576 과 같은 오류를 방지합니다.

• 기본 파일 위치: file_output 경로를 지정하지 않으면 이미지는 고유한 파일 이름으로 /tmp (또는 MCP_HF_WORK_DIR 환경 변수로 설정한 디렉토리)에 저장됩니다.

• 환경 변수:

  • MCP_HF_WORK_DIR : 대용량 이미지와 파일 출력이 저장되는 위치를 제어합니다. 예: export MCP_HF_WORK_DIR=/your/desired/dir

• 모범 사례: 대용량 이미지나 프로덕션 이미지의 경우 항상 파일 출력을 사용하고 클라이언트가 파일 경로를 처리하도록 구성되어 있는지 확인하세요.

📚 참고문헌

• OpenAI 이미지 API 문서

🙏 크레딧

• @modelcontextprotocol/sdk 로 빌드됨

• OpenAI Node.js SDK를 사용합니다

• SureScale.ai 에서 구축