imaginate-mcp

OpenAI GPT Image와 Google Gemini(Nano Banana)로 이미지를 생성하고 편집하는 MCP 서버입니다. stdio로 실행되며 모든 이미지를 디스크에 저장하고, 어시스턴트가 결과물로 계속 작업할 수 있도록 파일 경로를 돌려줍니다.

제공 도구

공급자별로 나뉜 여섯 개 도구:

구성한 키에 해당하는 도구만 등록됩니다. OPENAI_API_KEY만 설정하면 어시스턴트는 세 개 도구만 보게 되며, Google 키가 없어서 실패하는 도구는 하나도 없습니다. 이것이 provider 인자를 받는 도구 하나 대신 공급자별로 도구를 나눈 주된 이유입니다.

Related MCP server: OpenAI Image Generation MCP Server

요구 사항

• Node.js 20 이상

• OpenAI API 키, Gemini API 키, 또는 둘 다

GPT Image 모델은 OpenAI API 조직 인증(organization verification)이 필요합니다. 인증을 완료하지 않았다면 OpenAI가 요청을 거부하며, 서버가 그 사실을 알려줍니다.

연결하기

npx로 배포된 패키지를 실행하세요. 저장소를 클론하거나 패키지를 전역으로 설치할 필요가 없습니다.

npx -y @pinkpixel/imaginate-mcp

서버를 클라이언트 설정에 추가하세요. Claude Desktop은 claude_desktop_config.json을 편집하고, Claude Code는 프로젝트의 .mcp.json 또는 사용자 설정 파일을 사용하세요.

{
  "mcpServers": {
    "imaginate": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/imaginate-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "GEMINI_API_KEY": "...",
        "IMAGINATE_OUTPUT_DIR": "~/Pictures/imaginate"
      }
    }
  }
}

설정을 편집한 후 클라이언트를 다시 시작하세요. 이미지 도구가 나타나지 않으면 imaginate_setup_help를 호출하세요. 이 도구는 공급자 키가 하나도 발견되지 않았을 때만 존재하며, 아직 설정해야 할 변수 목록을 보여줍니다.

소스에서 실행하기

서버를 로컬에서 작업하려면 저장소를 clone하고 빌드하세요.

git clone https://github.com/pinkpixel-dev/imaginate-mcp.git
cd imaginate-mcp
npm install
npm run build
node dist/index.js

이 빌드에 MCP 클라이언트를 연결하려면 "command": "node"를 사용하고 args에 dist/index.js의 절대 경로를 설정하세요.

환경 설정

모든 변수는 시작할 때 한 번만 읽으므로, 변수를 변경한 후에는 클라이언트를 다시 시작하세요.

모든 도구 호출에서 output_dir로 출력 디렉터리를, filename으로 파일 이름을 재정의할 수 있습니다.

파일 처리 방식

이미지는 출력 디렉터리에 저장됩니다. 서버는 어떤 파일도 덮어쓰지 않습니다. 이미 cat.png가 존재하면 cat-1.png, cat-2.png 순서로 저장됩니다.

기본 이름은 openai-a-red-fox-20260825-134512-071.png처럼 보입니다. 이는 공급자 접두사, 프롬프트의 슬러그(slug), 타임스탬프 순서로 구성됩니다. 특정 이름이 필요하다면 filename을 전달하세요.

편집에 사용하는 원본 이미지는 로컬 파일이어야 합니다. 절대 경로를 전달하세요. 도구는 원격 URL을 다운로드하지 않으므로, 웹에 있는 파일이라면 먼저 파일을 내려받아야 합니다. 원본 파일은 읽기 전용이며 절대 수정되지 않습니다.

사용하기

서버가 연결되면 평소처럼 어시스턴트에게 지시하면 됩니다. 몇 가지 알아두면 좋은 점이 있습니다.

공급자 선택

두 공급자 모두 장점이 있지만 강점은 서로 다릅니다.

Gemini는 이미지 속 텍스트, 세계 지식, 인포그래픽 작업에 더 강하며, 그림을 그리기 전에 실시간 Google 검색 결과를 grounding으로 사용할 수 있습니다. 그리고 인터랙션 ID를 반환하므로 이미지를 다시 업로드하지 않고도 계속해서 다듬을 수 있습니다.

GPT Image는 상세한 레이아웃 지침을 잘 따르고, 크기·품질·배경을 세밀하게 제어해 줍니다. 투명한 배경이 필요할 때 사용할 모델이며, 다만 gpt-image-2에서 투명 배경 지원이 빠졌기 때문에 gpt-image-1.5 같은 이전 모델이 필요합니다.

Gemini 이미지 반복 다듬기

모든 Gemini 결과에는 인터랙션 ID가 포함됩니다. 다음 gemini_edit_image 호출에서 이 값을 previous_interaction_id로 전달하면 이미지를 다시 보내지 않아도 됩니다.

1. 원하는 프롬프트로 gemini_generate_image를 호출합니다. 결과에 인터랙션 ID가 포함됩니다.

2. previous_interaction_id와 함께 "가로로 만들어 줘." 같은 프롬프트로 gemini_edit_image를 호출합니다.

이 방식은 다시 업로드를 건너뛰어 비용이 덜 들고, 여러 번 반복해도 이미지가 더 일관되게 유지됩니다.

편집과 합성

두 *_edit_image 도구는 같은 인터페이스로 여러 작업을 처리합니다. 이미지 경로를 하나 전달하면 해당 이미지를 편집하고, 여러 개를 전달하면 새로운 장면으로 합성합니다.

마스크 인페인팅의 경우 두 공급자는 방식이 다릅니다. OpenAI는 알파 채널이 있는 실제 마스크 PNG를 mask로 전달해야 합니다. Gemini는 의미론적으로 처리하므로 "하늘만 바꾸고 나머지는 전부 똑같이 유지해 줘"라고 말하면 마스크 파일이 필요하지 않습니다.

참조 이미지 수 제한은 Gemini 모델에 따라 다릅니다. Lite는 14개, Nano Banana 2는 10개, Pro는 6개입니다. 확실하지 않으면 gemini_list_image_models를 호출하세요.

개발

npm run build      # compile to dist/
npm run watch      # compile on change
npm run typecheck  # types only, no output
npm test           # compile tests and run them

테스트는 내장 Node.js 테스트 러너를 사용합니다. 테스트는 파일 이름 지정 및 저장 로직, Gemini 응답 파싱, 오류 메시지 매핑을 다룹니다. 두 API 모두 호출하지 않으므로 키 없이도 실행할 수 있습니다.

디렉터리 구조:

src/
  index.ts               entry point, conditional tool registration
  config.ts              environment parsing
  lib/                   file handling, errors, result formatting, model catalog
  providers/openai/      OpenAI client wrapper and tool definitions
  providers/google/      Gemini client wrapper and tool definitions
tests/

제한 사항

• 원본 이미지는 로컬 파일이어야 합니다. 원격 URL은 지원하지 않습니다.

• 스트리밍 및 중간 이미지는 연결되어 있지 않습니다. 호출은 이미지가 완성되면 반환됩니다.

• Gemini는 요청한 이미지 개수를 안정적으로 지키지 않으므로 호출당 하나의 이미지를 요청하세요. OpenAI 도구는 n 인자를 받으며 정상 동작합니다.

• OpenAI는 복잡한 프롬프트에 최대 2분까지 걸릴 수 있습니다. 이는 서버가 아니라 API의 특성입니다.

• 모든 Gemini 이미지에는 보이지 않는 SynthID 워터마크가 포함됩니다.

• 모델 ID와 가격은 두 공급자 모두 빠르게 변합니다. 목록 도구가 보여주는 정보는 이 버전이 알고 있는 내용이며 실제 사용할 수 있는 모델과 차이가 있을 수 있습니다.

라이선스

Apache 2.0. LICENSE를 참조하세요.

💖을 담아 Pink Pixel이 만들었습니다.