Gemini Image MCP

Google의 Gemini 이미지 모델(Nano Banana, Nano Banana 2, Nano Banana Pro)을 사용하여 이미지를 생성하고 편집하기 위한 MCP 서버입니다. 하나의 도구인 generate_image를 제공하며, Claude, Codex, Cline과 같은 AI 도구가 사용자의 API 키를 사용하여 호출할 수 있습니다.

기능

• generate_image는 텍스트-이미지 생성, 편집 및 합성을 처리합니다(참조 이미지(로컬 파일 경로 또는 base64)를 전달하면 가능).

• 모든 생성 매개변수는 호출 시 노출됩니다: temperature (1), topP (0.95), topK, maxOutputTokens (flash/lite의 경우 65536, pro의 경우 32768), seed, stopSequences, presencePenalty, frequencyPenalty, systemInstruction, thinkingLevel (minimal/high), thinkingBudget, enableGoogleSearch (기본값 true), imageSize (512/1K/2K/4K), aspectRatio (기본값 "auto" + 표준 비율), personGeneration.

• instructions 블록과 매개변수별 설명을 제공하여 MCP 클라이언트가 추가 프롬프트 없이 도구 사용 방법을 파악할 수 있도록 합니다.

• 이미지를 디스크에 저장하고 파일 경로를 반환합니다. 응답에 base64를 포함하지 않으므로 4K 이미지가 클라이언트의 컨텍스트 창을 차지하지 않습니다.

• 오류는 힌트(잘못된 키, 속도 제한, 안전 차단, 알 수 없는 모델)와 함께 반환되며, 원시 API 덤프가 아닙니다.

• stdio 전송을 사용하며, 로컬 MCP 서버의 일반적인 설정입니다.

요구 사항

• Bun 1.0+

• https://aistudio.google.com/apikey에서 발급받은 Gemini API 키

설치

bun install

설정

세 가지 환경 변수로, 일반적으로 MCP 클라이언트의 구성 파일에 설정합니다:

선택 가능한 모델:

모델은 models/ 접두사와 함께 지정할 수도 있습니다(예: models/gemini-3.1-flash-image).

클라이언트 설정

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json에 다음을 추가하세요:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gemini-image-mcp/index.ts"],
      "env": {
        "GEMINI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Cline (VS Code)

cline_mcp_settings.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gemini-image-mcp/index.ts"],
      "env": {
        "GEMINI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.gemini-image]
command = "bun"
args = ["run", "/absolute/path/to/gemini-image-mcp/index.ts"]
env = { GEMINI_API_KEY = "YOUR_KEY_HERE" }

npm (bunx/npx) 사용

패키지가 게시된 후, 클라이언트를 bunx로 지정하세요:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bunx",
      "args": ["gemini-image-mcp"],
      "env": { "GEMINI_API_KEY": "YOUR_KEY_HERE" }
    }
  }
}

generate_image 매개변수

prompt만 필수입니다. 나머지는 이미지 생성에 적합한 기본값으로 설정됩니다.

도구는 저장된 파일 경로, 모델, 유효 구성 및 토큰 사용량을 포함한 텍스트 요약을 반환합니다. 이미지 데이터를 인라인으로 반환하지 않습니다. 파일을 열어 결과를 확인하세요.

AI에게 요청할 수 있는 작업

• "비 오는 도쿄 거리의 야경, 시네마틱 네온 조명이 있는 16:9 히어로 이미지를 생성해 줘."

• "/tmp/product.png를 편집해 줘: 대리석 테이블 위에 놓고 부드러운 아침 빛으로" (이것은 referenceImages를 사용합니다).

• "gemini-3-pro-image를 사용하여 정확한 헤드라인 'LAUNCH DAY'가 포함된 4K 포스터를 생성해 줘."

개발

bun test              # unit tests (config, schema, request/response parsing)
bun run typecheck     # tsc --noEmit
bun run inspector     # interactive MCP inspector (needs GEMINI_API_KEY)
bun run start         # run the server on stdio

문제 해결

• "Gemini API 키 누락": 클라이언트의 MCP 구성에 있는 env 블록에 GEMINI_API_KEY를 넣으세요. Claude Desktop과 같은 GUI 앱은 셸 환경을 읽지 않으므로 셸에 설정하는 것만으로는 충분하지 않습니다.

• 안전 차단: 프롬프트를 다시 작성하세요. 사람이 관련된 경우 personGeneration을 확인하세요.

• 429 / 할당량 초과: 잠시 기다렸다가 다시 시도하거나, 할당량이 더 높은 gemini-3.1-flash-image를 사용하세요.

• 로그: 서버는 stderr에만 로그를 기록합니다. stdout은 MCP 프로토콜을 전달하므로 console.log를 추가하지 마세요.

저자

Thomi Jasir dev@venobi.com

라이선스

MIT