gemini-image-mcp

A standalone, user-scoped Model Context Protocol server that lets Claude Code generate and edit images with Google's Gemini image models (Nano Banana / Nano Banana Pro) and Imagen 4 — running on Vertex AI with Application Default Credentials (ADC). No API key, no JSON key file.

• Default model: nano-banana = Gemini 2.5 Flash Image (GA).
• Also exposed: nano-banana-pro (Gemini 3 Pro Image, preview) and the imagen-4* family.
• Transport: stdio (local) or streamable-http (remote), via the official Python MCP SDK (FastMCP).
• Auth: Vertex AI + ADC only. You bring your own GCP project.

Quick start (one command, no clone)

uvx fetches and runs the server straight from GitHub — nothing to clone or install. Register it with Claude Code at user scope in a single command:

claude mcp add gemini-image -s user \
  -e GOOGLE_CLOUD_PROJECT=your-gcp-project-id \
  -- uvx --from git+https://github.com/someshwarpatil/gemini-image-mcp.git gemini-image-mcp

Then authenticate once with ADC and restart Claude Code:

gcloud auth application-default login

Prereqs: Python 3.12 + uv, the gcloud CLI, and a GCP project with the Vertex AI API enabled. Verify with claude mcp list / claude mcp get gemini-image.

How it works

The server runs as its own process (Claude Code spawns it over stdio). Because it is a separate process, it cannot see the client's per-session scratchpad — so every tool takes an explicit output_dir. The full-resolution PNG is always saved to disk and its absolute path is always returned. A small downscaled preview image is returned only when return_image=True, to protect the client's token budget (a full-res MCP image can cost ~15-25k tokens).

Setup from a clone (for development)

git clone https://github.com/someshwarpatil/gemini-image-mcp.git
cd gemini-image-mcp

# One command: sync deps + check ADC + register with Claude Code.
GOOGLE_CLOUD_PROJECT=your-gcp-project-id ./scripts/setup.sh

scripts/setup.sh runs uv sync, checks ADC, and registers the server at user scope (idempotent — safe to re-run). Or do it manually:

uv sync
gcloud auth application-default login          # one-time ADC; no API key, no JSON key file
export GOOGLE_CLOUD_PROJECT=your-gcp-project-id

Prefer a file over shell exports? Copy .env.example → .env and fill in your values (.env is gitignored).

Environment

Variable	Default	Purpose
GOOGLE_CLOUD_PROJECT	(auto-detected from ADC / gcloud)	GCP project serving the Vertex image models.
GOOGLE_CLOUD_LOCATION	global	Vertex location for the Gemini models. Gemini image models are global-only on Vertex — leave as global.
GEMINI_IMAGE_IMAGEN_LOCATION	us-central1	Vertex location for the Imagen models (Imagen is not served on global).
GEMINI_IMAGE_OUTPUT_DIR	(unset)	Default dir for saved PNGs when a call omits output_dir. Falls back to the server CWD.
GEMINI_IMAGE_LOG_LEVEL	INFO	stderr log level for the server (DEBUG/INFO/WARNING/ERROR).
GEMINI_IMAGE_RETURN_MODE	file	file (save + path, local) · inline (image bytes) · gcs (upload + signed URL — best for the Claude apps).
GEMINI_IMAGE_GCS_BUCKET	(unset)	Private bucket for gcs mode. Objects are v4-signed (not public); pair with a lifecycle delete rule.
GEMINI_IMAGE_GCS_TTL_DAYS	7	Signed-URL lifetime (days) for gcs mode.

output_dir resolution order: explicit tool argument → GEMINI_IMAGE_OUTPUT_DIR → process CWD.

Models

Pass the friendly alias — never the raw model id.

Alias	Vertex model id	Family	Edit?	Location	Notes
nano-banana	gemini-2.5-flash-image	gemini	yes	global	Default. GA. text→image + edit/fusion.
nano-banana-pro	gemini-3-pro-image-preview	gemini	yes	global	Preview on Vertex; up to 14 ref images, up to 4K. May 404 if the project isn't gated.
imagen-4	imagen-4.0-generate-001	imagen	no	us-central1	GA standard. text→image only. Deprecation risk (~2026-06-30).
imagen-4-fast	imagen-4.0-fast-generate-001	imagen	no	us-central1	GA fast/low-cost. text→image only.
imagen-4-ultra	imagen-4.0-ultra-generate-001	imagen	no	us-central1	GA highest quality. n=1 only.

Gemini aspect ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9. Imagen aspect ratios: 1:1, 3:4, 4:3, 9:16, 16:9.

The Gemini models are the durable path. The imagen-4* aliases are best-effort: Imagen 4 had an announced EOL around 2026-06-30 and may fail at runtime — the underlying Vertex error is surfaced verbatim.

Tools

• generate_image(prompt, model="nano-banana", aspect_ratio="1:1", n=1, output_dir=None, return_image=True) Text → image. For Gemini, n>1 loops one image per call; Imagen uses native batching (imagen-4-ultra is capped at 1). n is capped at 8 per call — each image is a separately billed generation.
• edit_image(image_paths, prompt, model="nano-banana", output_dir=None, return_image=True) Image(s) + instruction → image. One input = edit, two or more = fusion. Gemini aliases only — imagen-4* is rejected with a clear error.
• list_models() — the alias table + notes (cheap, offline).

Register with Claude Code (from a clone)

The Quick start uvx command needs no clone. If you've cloned the repo instead, use the tracked script — it derives the repo path automatically and reads your project from the environment. ~/.claude.json is not committed.

GOOGLE_CLOUD_PROJECT=your-gcp-project-id bash scripts/register.sh

Equivalent raw command:

claude mcp add gemini-image \
  -e GOOGLE_CLOUD_PROJECT=your-gcp-project-id \
  -e GOOGLE_CLOUD_LOCATION=global \
  --scope user \
  -- uv --directory /path/to/gemini-image-mcp run gemini-image-mcp

--scope user is placed after the -e flags and immediately before the name (the CLI rejects a name right after -e). -t stdio is implied by the -- <command> form. Verify with claude mcp list and claude mcp get gemini-image.

Remote deployment (Cloud Run / AWS / your VM)

Run the same server over streamable-http so the Claude apps (web / desktop / mobile) can use it as a custom connector and generate images directly in chat. Because a remote client can't read the server's disk, set the return mode to send the image back: gcs uploads each image to a private bucket and returns a signed URL (the reliable choice — the Claude apps don't render inline MCP image blocks), or inline returns the raw bytes for clients that do. The Cloud Run deploy below uses gcs.

Auth reality: claude.ai custom connectors send no static bearer token and must reach a public URL. So the deployment is public, guarded by a secret path: the MCP endpoint lives at /<secret>/mcp and the whole URL is the credential. Keep it secret; rotate it (new secret + redeploy) if it leaks. The service scales to zero and caps max-instances to bound cost. For stronger auth, front it with OAuth 2.1 or an API gateway.

Any container host (Docker)

docker build -t gemini-image-mcp .
docker run -p 8080:8080 \
  -e GOOGLE_CLOUD_PROJECT=your-gcp-project-id \
  -e GEMINI_IMAGE_RETURN_MODE=inline \
  -e MCP_PATH_SECRET="$(openssl rand -hex 24)" \
  gemini-image-mcp
# endpoint: http://localhost:8080/<secret>/mcp

On AWS / your own VM, front it with TLS (connectors require https) via your load balancer or reverse proxy, and supply ADC through the platform's workload identity or a service account — never a committed key file.

Google Cloud Run (scripted)

GOOGLE_CLOUD_PROJECT=your-gcp-project-id ./scripts/deploy_cloudrun.sh

The script enables the required APIs, mints a secret path token in Secret Manager, grants the Cloud Run runtime service account roles/aiplatform.user (Vertex via ADC — no key files) plus secret access, builds from source, and deploys public + scale-to-zero + max 2 instances. It prints the connector URL (https://<service>/<secret>/mcp). On Cloud Run, ADC is the service account automatically.

Add it as a Claude connector

1. claude.ai (or the Claude desktop app) → Settings → Connectors → Add custom connector.
2. Paste the connector URL (https://<service>/<secret>/mcp); leave auth as none.
3. Add, then in a chat ask Claude to "generate an image of …" — it calls generate_image and returns a viewable signed-URL link to the picture. Works on web, desktop, and mobile.

Verify a deployment

uv run python scripts/smoke_remote.py "https://<service>/<secret>/mcp"                         # list tools
uv run python scripts/smoke_remote.py "https://<service>/<secret>/mcp" --generate "a red panda"  # one image

Notes & caveats

• SynthID watermark: all Gemini image output carries an invisible SynthID watermark. This is not optional.
• Data residency: global does not satisfy data-residency requirements and has separate quotas from regional endpoints. Fine for most personal/dev use.
• Previews may not render inline in every Claude Code build and can be token-expensive — which is exactly why the full-res file is always on disk and the path is always returned.
• stdio vs remote: the stdio server (Quick start) targets Claude Code (terminal + IDE) and, via its own config, the Claude desktop app. For the Claude apps (web/desktop/mobile) and generating images in chat, deploy the HTTP server — see Remote deployment.

License

MIT.