Claude Desktop Code용 GPT Image 2 플러그인

번들로 제공되는 로컬 MCP 서버를 통해 OpenAI GPT Image 2로 프로젝트 이미지를 생성하고 편집합니다. 플러그인은 유료 호출당 하나의 검증된 이미지를 작성하고, 승인된 프로젝트 워크스페이스 내에 파일을 보관하며, 기존 대상을 덮어쓰지 않습니다.

简体中文

지원되는 Claude 표면

이 플러그인은 Claude Desktop Code, 즉 Claude Desktop 애플리케이션의 프로젝트 중심 Code 경험을 위한 것입니다. Claude Desktop Chat은 지원되지 않습니다. MCPB 패키지가 아니며 원격 MCP 서비스가 아닙니다.

Related MCP server: mcp-openai-images-audio

Claude Desktop Code GUI를 통해 설치

GUI 플러그인 설치가 기본 경로입니다:

1. Claude Desktop Code에서 대상 프로젝트를 엽니다.

2. GUI 설정 → 플러그인 영역을 엽니다. 레이블은 Claude 릴리스에 따라 약간 다를 수 있습니다.

3. 이 저장소 루트를 로컬 마켓플레이스로 추가하거나 저장소 소스를 선택한 다음 gpt-image-2@kpk-plugins를 설치합니다.

4. 현재 프로젝트에 대해 설치된 플러그인을 활성화합니다. 활성화는 프로젝트별로 이루어집니다. 설치한다고 모든 프로젝트에 자동으로 액세스 권한이 부여되지는 않습니다.

5. 구성을 위해 플러그인 설정을 엽니다. .mcp.json을 일반 설정에 복사하지 마십시오.

플러그인 루트는 마켓플레이스 루트이며, 마켓플레이스 진입점은 ./를 가리킵니다.

런타임 요구 사항

유일한 런타임 종속성은 Claude Desktop Code에서 볼 수 있는 PATH에 있는 **Node.js 20+**입니다. 설치된 플러그인은 사전 빌드된 dist/server.mjs를 직접 시작합니다. 런타임에 플러그인은 npm, npx, 라이프사이클 스크립트, 소스 컴파일을 실행하거나 node_modules를 로드하지 않습니다.

커밋된 마켓플레이스 복사본에는 독립 실행형 번들이 포함되어 있습니다. 설치된 복사본 테스트는 Git 추적 파일만 실행하고 node_modules 디렉터리와 API 키 없이 get_status가 작동하는지 확인합니다.

npm 및 개발 종속성은 소스 체크아웃을 빌드하거나 테스트하는 기여자에게만 필요합니다.

GUI에서 구성

플러그인 설정에서 민감한 OpenAI API 키 필드에 API 키를 입력합니다. 명령줄, .env, .mcp.json, 일반 설정, README, 프롬프트 또는 로그에 넣지 말고 Claude에게 표시하거나 검사하도록 요청하지 마십시오.

기본 공식 Base URL은 다음과 같습니다:

https://api.openai.com/v1

사용자 정의 Base URL은 이 플러그인이 보내는 API 키, 프롬프트 및 편집 이미지를 수신합니다. 해당 엔드포인트와 운영자를 신뢰하는 경우에만 구성하십시오. 사용자 정의 엔드포인트는 일반적으로 /v1을 포함해야 합니다. 플러그인이 자동으로 추가하지 않습니다. 사용자에게 제공되는 유일한 문서 예제는 다음과 같습니다:

https://api.example.invalid/v1

URL은 자격 증명, 쿼리, 프래그먼트, 제어 문자 또는 주변 공백이 없는 절대 HTTP(S) URL이어야 합니다. 호환 가능한 엔드포인트는 OpenAI 클라이언트에서 사용하는 이미지 API를 구현해야 합니다. URL을 수락한다고 해서 호환성이 암시되지는 않습니다.

HTTP는 신뢰할 수 있는 로컬 또는 사설 네트워크 호환 엔드포인트에 허용되지만, 전송 암호화 없이 API 키, 프롬프트 및 편집 이미지를 전송합니다. 신뢰하는 네트워크 및 엔드포인트에서만 http:// Base URL을 사용하고, 그 외에는 HTTPS를 선호하십시오.

설치 후 /gpt-image-2:setup을 실행합니다. 이 명령은 get_status만 호출하며 공급자 요청을 하지 않습니다.

도구

get_status

안전한 상태 데이터만 보고합니다: API 키 구성 여부(boolean), 사용자 정의 Base URL 구성 여부, 실행 중인 서버의 활성 URL에 대한 base_url_valid: true, 승인된 워크스페이스 루트, 모델, 서버 버전 및 기본 상대 출력 디렉터리. 잘못 구성된 Base URL은 서버 시작을 방지합니다. 플러그인 설정에서 수정하고 플러그인을 다시 로드하거나 다시 시작하십시오. get_status는 공급자 또는 이미지 API 요청을 전혀 하지 않으며 키나 Base URL 값을 반환하지 않습니다.

generate_image

모델 gpt-image-2, 고정 n: 1로 하나의 이미지를 생성하고 새 파일 하나를 저장합니다. 주요 입력은 다음과 같습니다:

• prompt

• quality: auto, low, medium 또는 high

• size

• output_format: png, jpeg 또는 webp

• 선택적 JPEG/WebP output_compression (0~100)

• moderation: auto 또는 low

• 선택적 상대 output_path 및 승인된 workspace_root

edit_image

제공된 순서대로 1~8개의 편집 입력을 편집하고 새 이미지 하나를 저장합니다. 입력은 PNG, JPEG 또는 WebP일 수 있습니다. 제한은 입력당 50MiB이며 모든 편집 이미지와 선택적 마스크를 합쳐 200MiB입니다.

선택적 마스크는 알파 채널이 있는 PNG여야 하며, 첫 번째 입력 이미지의 크기와 일치해야 하고, 4MiB 미만이어야 합니다. 투명한 출력 배경은 지원되지 않습니다. 마스크 알파는 편집 영역만 식별합니다.

형식, 크기 및 출력

• 출력 형식: PNG, JPEG 및 WebP.

• 도구 기본 크기는 1024x1024입니다. auto도 허용됩니다.

• 사용자 정의 WIDTHxHEIGHT는 16의 배수를 사용해야 하며, 각 변은 최대 3840픽셀이어야 하고, 종횡비는 1:3에서 3:1 사이여야 하며, 총 픽셀 수는 655,360에서 8,294,400 사이여야 합니다.

• PNG는 출력 압축을 사용하지 않습니다. JPEG 및 WebP는 0에서 100까지의 압축 값을 허용합니다.

• output_path가 생략되면 출력은 고유한 프롬프트 없는 파일 이름으로 .claude/generated-images/gpt-image-2 아래에 저장됩니다.

• 명시적 출력 경로는 유지되며, 승인된 워크스페이스 루트를 기준으로 한 상대 경로여야 하고, 요청된 형식과 일치하는 확장자를 사용해야 합니다.

• 기존 대상은 거부됩니다. 덮어쓰지 않는 게시는 동시 호출이 동일한 대상을 대체하는 것을 방지합니다.

실제 크기는 저장된 이미지가 디코딩되고 검증된 후에 유지 및 보고됩니다. 명시적으로 요청된 크기가 다른 경우 파일은 실제 크기로 저장된 상태로 유지되며 결과에 SIZE_MISMATCH가 포함됩니다.

2MiB 이하의 이미지에는 인라인 미리보기가 포함됩니다. 더 큰 이미지의 경우 인라인 미리보기가 생략됩니다. 저장된 파일 경로가 권위를 유지합니다. TEMP_CLEANUP_PENDING은 출력이 성공적으로 저장되었지만 임시 게시 파일의 정리가 아직 보류 중임을 의미합니다.

비용, 동시성 및 재시도

생성 및 편집은 유료 공급자 작업입니다. 플러그인은 요청당 하나의 출력을 고정하고 각 서버 프로세스에서 한 번에 하나의 유료 호출을 허용합니다. SDK 재시도 및 애플리케이션 재시도가 없으므로 실패한 유료 호출이 자동으로 반복되지 않습니다. 이미지 도구를 호출하기 전에 프롬프트, 편집 입력, 크기, 형식 및 출력 경로를 확인하십시오.

워크스페이스 및 보안 경계

• 출력은 Claude Desktop Code에서 승인한 워크스페이스 루트 내에 유지됩니다. 출력 경로는 절대 경로이거나 루트 외부로 이동할 수 없습니다.

• 포함된 절대 입력 경로는 이미 승인된 루트 내에서 확인되는 경우에만 허용됩니다. 입력 경로는 새 루트를 부여하지 않습니다.

• 입력 파일은 업로드 전에 안정적인 핸들을 통해 개인 임시 스냅샷으로 복사됩니다. 원본은 수정되지 않습니다.

• 공급자 출력은 엄격하게 디코딩되고, 이미지 검증되고, 플러시되며, 덮어쓰지 않는 의미 체계로 게시됩니다.

• 로그는 제한된 상태 코드와 숫자 컨텍스트만 허용합니다. 프롬프트, API 키, Base URL, 이미지 데이터, Base64 및 전체 입력 경로는 제외됩니다.

Windows Node 20 정션 경계

Windows에서 Node 20에서 기존 재분석 지점/정션 이스케이프는 거부되며, 출력 상위 경로는 독점 게시 직전에 다시 확인됩니다. 검사 사이에 동일한 권한의 다른 프로세스에 의한 활성 디렉터리 교체는 위협 경계 밖에 남아 있습니다. 해당 동일 권한 교체 경합을 완전히 제거하려면 네이티브 Win32 핸들 상대 도우미가 필요합니다.

문제 해결

• API 키가 구성되지 않음: Claude Desktop Code 플러그인 설정을 열고 민감한 API 키 필드를 채우십시오. 키를 채팅이나 셸에 붙여넣지 마십시오.

• 잘못되었거나 사용되지 않는 사용자 정의 Base URL: 잘못 구성된 Base URL은 서버 시작을 방지합니다. 플러그인 설정에서 수정하고 설정이 저장되었는지 확인한 다음 플러그인을 다시 로드하거나 다시 시작하십시오. 사용자 정의 엔드포인트는 일반적으로 /v1로 끝나야 합니다. /v1 세그먼트가 자동으로 추가되지 않습니다.

• 승인된 워크스페이스 루트 없음: Claude Desktop Code에서 프로젝트를 열고 해당 프로젝트에 대해 플러그인을 활성화하십시오.

• OUTPUT_EXISTS: 새 상대 출력 경로를 선택하십시오. 플러그인이 덮어쓰지 않습니다.

• SIZE_MISMATCH: 반환된 실제 너비와 높이를 사용하십시오. 저장된 이미지는 유효합니다.

• 미리보기 생략됨: 반환된 상대 또는 절대 경로를 여십시오. 인라인 미리보기는 2MiB로 제한됩니다.

소스에서 빌드 및 테스트

개발 명령은 개발 종속성을 설치하고 사용할 수 있습니다. 이는 설치된 플러그인 런타임 동작의 일부가 아닙니다. 검증 명령은 승인된 스크립트 세트가 정확한지 확인하기 전에 암시적 npm 라이프사이클 후크를 비활성화합니다.

npm ci --ignore-scripts
npm run typecheck
npm test
npm run build
npm run test:dist
npm --ignore-scripts run validate

이러한 검사는 로컬 픽스처, 페이크 및 프로토콜 테스트를 사용합니다. 유료 이미지 요청이 필요하지 않습니다. 라이브 공급자 검증이 수행되거나 주장되지 않았습니다.

라이선스

MIT © 2026 KPK. LICENSE 및 THIRD_PARTY_NOTICES.md를 참조하십시오.