image-gen-mcp

Gemini의 네이티브 이미지 모델("Nano Banana")로 이미지를 생성하고, Streamable HTTP로 제공되는 MCP 서버입니다.

도구는 generate_image 하나뿐입니다. 상태도 어디에도 없고 자체 인증도 없습니다. 프로덕션에서는 mcp-oauth-proxy 뒷단에서 백엔드로 실행되며, cloudrun-mcp-deployment에 의해 배포됩니다.

DESIGN.md는 왜 이렇게 구성했는지 설명하고, 이 파일은 어떻게 실행하는지 설명합니다.

빠른 시작(로컬, 토큰 인증)

uv sync
export GEMINI_API_KEY="…"                       # from Google AI Studio
export IMAGE_MCP_TOKEN="$(openssl rand -base64 32)"
uv run python -m image_gen_mcp

클라이언트를 http://127.0.0.1:8080/mcp에 Authorization: Bearer $IMAGE_MCP_TOKEN 헤더로 연결하세요. Claude Code의 경우:

claude mcp add --transport http image-gen http://127.0.0.1:8080/mcp \
  --header "Authorization: Bearer $IMAGE_MCP_TOKEN"

Related MCP server: Imagen MCP Server

도구

generate_image(prompt, aspect_ratio="1:1", image_size="1K", model=None)

IMAGE_MCP_INLINE_MAX_BYTES(기본값 1.5MB) 이하인 이미지는 인라인으로 반환되어 채팅에서 렌더링됩니다. 더 큰 이미지는 Cloud Storage에 업로드되고 서명된 URL로 반환됩니다. 구조화된 출력은 항상 실제 픽셀 크기, 사용된 모델, 그리고 어떤 전달 경로를 사용했는지를 보고합니다.

모델 / 해상도 지원

지원되지 않는 조합은 30초의 왕복 후가 아니라 도구 경계에서 밀리초 단위로 거부되며, 무엇이 지원되는지 알려주는 메시지가 함께 반환됩니다.

구성

모든 설정은 환경에서 비롯됩니다. 주석이 달린 목록은 .env.example을 참조하세요. 핵심은 다음과 같습니다.

서버는 잘못 설정된 채로 실행되지 않습니다. API 키가 없거나 인증 경계가 전혀 없는 상태(정적 토큰도 프록시 모드도 아닌 상태)는 모두 기동 실패입니다.

인증

두 가지 형태가 있으며, 둘 다 해당하지 않으면 서버는 시작을 거부합니다.

프록시 뒤(프로덕션). IMAGE_MCP_TRUST_PROXY_HEADERS=1로 설정하세요. 프록시가 Google 기준으로 사용자를 인증하고, 허용 목록을 적용하고, 클라이언트의 Authorization 헤더를 제거하고, 신원을 X-Auth-Email / X-Auth-Subject / X-Auth-Scope로 전달합니다. 이 서버는 이 헤더를 읽고 자체 토큰을 요구하지 않습니다. X-Auth-Email 없는 요청은 401을 받습니다.

헤더를 신뢰해도 안전한 것은 오직 이 프로세스에 다른 어떤 것도 도달할 수 없기 때문입니다. Cloud Run 멀티컨테이너 구성에서 백엔드는 인그레스(ingress) 포트를 선언하지 않으므로, 이 서버에 소켓을 열 수 있는 것은 같은 인스턴스의 프록시와 내부 스타트업 프로브뿐입니다. 라우팅 가능한 포트에서 이 기능을 켜지 마세요.

ALLOWED_EMAILS는 여기서 선택 사항이며 프록시의 허용 목록을 좁힙니다. 프록시가 도메인 전체를 승인하지만 이미지 생성 비용은 소수에게만 청구되어야 할 때 유용합니다. 설정하지 않았다면 "프록시로 들어온 사람"을 뜻합니다.

토큰(로컬, Claude Code). IMAGE_MCP_TRUST_PROXY_HEADERS는 설정하지 않고 IMAGE_MCP_TOKEN만 설정하세요. 호출자는 Authorization: Bearer <Token>을 보내며, X-Auth-* 헤더는 완전히 무시됩니다. 프록시가 없으면 그 헤더는 신뢰할 수 없는 요청 데이터일 뿐이기 때문입니다.

서버는 OAuth를 종료하지 않으며 /authorize, /token, /register 엔드포인트가 없습니다. GOOGLE_OAUTH_CLIENT_ID 또는 _SECRET을 설정하면 조용히 무시되는 게 아니라 시작 오류입니다. 그것들은 프록시가 할 일입니다.

이미지 빌드

.github/workflows/build.yml이 테스트를 실행하고 이미지를 빌드합니다. 그다음 GitHub Container Registry에 게시합니다. 배포는 하지 않습니다 — 배포는 별도 워크플로우나 다른 리포지토리가 처리합니다.

ghcr.io/ramzpat/image-gen-mcp로 게시됩니다. 구성할 것이 없습니다. 워크플로우는 내장된 GITHUB_TOKEN으로 인증합니다.

배포 워크플로우에서 사용하기

다이제스트(digest)로 배포하고 태그로 배포하지 마세요. 변경 가능한 태그(예: :latest) 앞에 있는 pull-through 캐시는 이전 이미지를 기꺼이 서빙할 수 있지만, 다이제스트는 낡을 일이 없습니다. 각 실행은 job summary에 다이제스트를 출력하며, 기본 빌드 워크플로우는 같은 파이프라인에서 빌드와 배포를 하고 싶다면 호출(callable)할 수 있습니다.

jobs:
  build:
    uses: ramzpat/image-gen-mcp/.github/workflows/build.yml@main
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "deploying ${{ needs.build.outputs.image }}@${{ needs.build.outputs.digest }}"

다른 리포지토리에서는 배포 시점에 다이제스트를 대신 확인하세요.

DIGEST=$(docker buildx imagetools inspect \
  ghcr.io/ramzpat/image-gen-mcp:latest --format '{{.Manifest.Digest}}')

GHCR 패키지는 기본값 비공개입니다. 다른 리포지토리의 배포 작업은 read:packages 권한이 있는 PAT를 사용하거나, GitHub 패키지 설정에서 패키지를 공개로 설정해야 합니다.

배포

cloudrun-mcp-deployment(.github/workflows/deploy-image-gen-mcp.yml)가 배포합니다. 이 워크플로우는 mcp-oauth-proxy를 앞에 둔 Cloud Run 멀티컨테이너 서비스의 백엔드 컨테이너로 이 이미지를 실행합니다. 그 리포지토리가 GCP 프로젝트, 리전, 허용 목록, 시크릿을 관리합니다. 여기는 이미지만 게시합니다.

해당 배포가 이 컨테이너에 설정하는 것은 다음과 같습니다.

HOST=0.0.0.0을 루프백 대신 쓰는 것은 필요이지 유출이 아닙니다. Cloud Run의 시작 프로브는 컨테이너 집 네임스페이스 밖에서 실행되며 루프백 전용 소켓에는 닿을 수 없습니다. 인그레스를 받는 컨테이너는 --port를 선언한 컨테이너(프록시)뿐이므로, 백엔드는 인스턴스 밖에서 접근 불가입니다.

2K/4K용 Cloud Storage

gcloud storage buckets create gs://BUCKET --uniform-bucket-level-access
gcloud storage buckets update gs://BUCKET \
  --lifecycle-file=<(echo '{"rule":[{"action":{"type":"Delete"},"condition":{"age":30}}]}')

# The runtime service account signs URLs through the IAM Credentials API,
# because it has no private key file. It needs this role *on itself*:
gcloud iam service-accounts add-iam-policy-binding RUNTIME_SA \
  --member="serviceAccount:RUNTIME_SA" --role=roles/iam.serviceAccountTokenCreator
gcloud storage buckets add-iam-policy-binding gs://BUCKET \
  --member="serviceAccount:RUNTIME_SA" --role=roles/storage.objectAdmin

serviceAccountTokenCreator 바인딩을 빼먹는 것이 서명 URL이 고장난 채 배포되는 가장 흔한 원인입니다.

테스트

uv run pytest -q

테스트 57개: 시작 가드, 두 형태의 신원 해석(프록시 헤더, 정적 토큰, 그리고 서로의 자격 증명을 무시하는지), 도구 검증과 전달, 실제 HTTP 위에서 uvicorn을 대상으로 실제 MCP 클라이언트가 토큰 모드와 프록시를 거치는 프로덕션 형태 양쪽에서 동작하는지를 확인하는 E2E 스모크 테스트입니다.

비용

허용 목록에 있는 사용자는 모두 하나의 API 키를 사용합니다. 실제로 도움이 되는 순서대로 나열하면 --max-instances, IMAGE_MCP_MAX_CONCURRENCY, GCP 결제 예산 알림, IMAGE_MCP_RATE_PER_HOUR입니다. 요율 제한은 인스턴스별로 계산되므로, 실제 상한은 IMAGE_MCP_RATE_PER_HOUR × --max-instances입니다.