Generate and edit images using Google's Gemini and Imagen models via Vertex AI.
Generate images (generate_image): Create full-resolution PNGs from text prompts. Choose from models like nano-banana (Gemini 2.5 Flash, default), nano-banana-pro, imagen-4, imagen-4-fast, or imagen-4-ultra. Configure aspect ratio and generate up to 8 images per call (imagen-4-ultra capped at 1). Optionally receive a downscaled inline preview to save token budget.
Edit or fuse images (edit_image, Gemini models only): Pass one image + prompt to edit, or multiple images + prompt to fuse/blend them. Supported on nano-banana and nano-banana-pro only.
List available models (list_models): Returns a table of all model aliases, their Vertex AI IDs, families, edit support, locations, and usage notes — no API call required.
Flexible output modes: Images can be saved to local disk (file), returned as inline bytes (inline), or provided as a signed GCS URL (gcs) for remote clients.
Authentication & deployment: Uses Application Default Credentials (ADC) — no API keys needed. Runs locally via stdio (Claude Code) or remotely via streamable-http (Cloud Run, Docker) for Claude web/desktop/mobile apps. Configured via environment variables for project, location, output directory, log level, and GCS bucket.
Generates and edits images using Google's Gemini image models (Nano Banana/Nano Banana Pro) and Imagen 4 on Vertex AI, with support for text-to-image, image editing, and fusion, returning full-resolution images saved to disk and optional previews.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gemini-image-mcp generate an image of a cat in a spacesuit"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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-mcpThen authenticate once with ADC and restart Claude Code:
gcloud auth application-default loginPrereqs: 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.
Related MCP server: Nano Banana Pro MCP Server
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).
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.shscripts/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-idPrefer a file over shell exports? Copy .env.example → .env and fill in your values
(.env is gitignored).
Variable | Default | Purpose |
| (auto-detected from ADC / gcloud) | GCP project serving the Vertex image models. |
|
| Vertex location for the Gemini models. Gemini image models are global-only on Vertex — leave as |
|
| Vertex location for the Imagen models (Imagen is not served on |
| (unset) | Default dir for saved PNGs when a call omits |
|
| stderr log level for the server ( |
|
|
|
| (unset) | Private bucket for |
|
| Signed-URL lifetime (days) for |
output_dir resolution order: explicit tool argument → GEMINI_IMAGE_OUTPUT_DIR → process CWD.
Pass the friendly alias — never the raw model id.
Alias | Vertex model id | Family | Edit? | Location | Notes |
|
| gemini | yes |
| Default. GA. text→image + edit/fusion. |
|
| gemini | yes |
| Preview on Vertex; up to 14 ref images, up to 4K. May 404 if the project isn't gated. |
|
| imagen | no |
| GA standard. text→image only. Deprecation risk (~2026-06-30). |
|
| imagen | no |
| GA fast/low-cost. text→image only. |
|
| imagen | no |
| GA highest quality. |
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.
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).
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.shEquivalent 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.
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.
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>/mcpOn 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_PROJECT=your-gcp-project-id ./scripts/deploy_cloudrun.shThe 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.
claude.ai (or the Claude desktop app) → Settings → Connectors → Add custom connector.
Paste the connector URL (https://<service>/<secret>/mcp); leave auth as none.
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.
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 imageSynthID 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.
MIT.
Edit or fuse input image(s) with an instruction (Gemini aliases only).
One input image = edit; two or more = fusion. Imagen models are text-to-image only
and are rejected here.
Args:
image_paths: Absolute paths to the input image(s).
prompt: The editing / fusion instruction.
model: nano-banana (default) or nano-banana-pro.
output_dir: Where to save the full-res PNG. Defaults to env
GEMINI_IMAGE_OUTPUT_DIR, else the server's CWD.
return_image: When True, append a downscaled preview of the result.
Returns:
A text line with the saved absolute path, optionally followed by a downscaled
preview Image.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | nano-banana | |
| prompt | Yes | ||
| output_dir | No | ||
| image_paths | Yes | ||
| return_image | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It discloses that the tool saves the result to a file, returns a path and optional preview. Describes default model and output directory fallback. Missing details about potential side effects or permission requirements, but transparent enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points for args. Front-loaded with core purpose and key differentiators. No unnecessary words. Efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description covers inputs, behavior, return format (path + optional image), and default behaviors. Complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate fully. It explains each parameter: image_paths (absolute paths), prompt (instruction), model (two named options), output_dir (defaults), return_image (boolean, preview). Adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Edit or fuse input image(s) with an instruction' and distinguishes between one image (edit) and two or more (fusion). It also warns that Imagen models are rejected, differentiating from sibling tool generate_image. Purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: one image = edit, two or more = fusion. Warns against using Imagen models. Lists parameters with defaults and behavior. Could be more explicit about when not to use (e.g., text-to-image use cases), but adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate image(s) from a text prompt.
Args:
prompt: The text description of the image to generate.
model: Friendly alias — nano-banana (default), nano-banana-pro, imagen-4,
imagen-4-fast, imagen-4-ultra. Call list_models for details.
aspect_ratio: e.g. "1:1", "16:9", "9:16". Allowed values depend on the model.
n: Number of images (Gemini loops one per call; imagen-4-ultra supports 1 only).
output_dir: Where to save the full-res PNG(s). Defaults to env
GEMINI_IMAGE_OUTPUT_DIR, else the server's CWD.
return_image: When True, append a downscaled preview of the first image.
Returns:
A list of text lines (one per saved absolute path), optionally followed by a
downscaled preview Image of the first result.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | ||
| model | No | nano-banana | |
| prompt | Yes | ||
| output_dir | No | ||
| aspect_ratio | No | 1:1 | |
| return_image | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses key behaviors: loop behavior for multiple images, per-model limits (imagen-4-ultra supports 1), file saving to output_dir with fallback defaults, and preview return via return_image. It could mention side effects of file writes explicitly, but overall it is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a one-line summary, detailed Args section, and Returns. It is longer but each sentence is informative. No redundancy; it could be slightly more concise in the Returns description, but overall well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters (1 required), no output schema, and no annotations, the description covers all input details, explains default behavior, and describes the return value (list of paths and optional image). It mentions limitations like model-specific constraints. It is complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must explain parameters. It does so thoroughly: prompt (text description), model (friendly aliases with examples), aspect_ratio (with examples and note on model-dependence), n (number with loop behavior), output_dir (default path logic), return_image (preview). This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Generate image(s) from a text prompt,' which is a clear, specific verb and resource. The sibling tools 'edit_image' and 'list_models' are distinct, so no confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description does not explicitly state when to use this tool versus siblings, the focus on generation from text prompts implicitly distinguishes it from editing or model listing. A more explicit usage guideline would be better but is not necessary given clear sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the friendly model aliases, their real Vertex ids, and usage notes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states the tool lists information but does not mention whether it is read-only, cached, or subject to any limitations. The output schema fills some gaps, but additional details on side effects or constraints would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately conveys the tool's purpose. No unnecessary words; every part is relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and the existence of an output schema, the description fully covers the tool's purpose and output. The context of sibling tools further clarifies its role. No additional details are needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is 100%. The description adds value by specifying what the output contains (friendly aliases, real IDs, usage notes), which is more than the empty schema provides. Baseline is 4 due to full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly uses the verb 'List' and specifies the exact resource: friendly model aliases, their real Vertex IDs, and usage notes. This distinguishes it from sibling tools that edit or generate images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Although no explicit when/when-not guidance is given, the context of sibling tools (edit_image, generate_image) makes it clear that this tool is for listing model information. A brief note on when to use it instead of other tools would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0edit_imagegenerate_imagelist_modelsScored across 3 tools
Each tool has a clearly distinct purpose: edit_image handles editing/fusion, generate_image handles generation from text, and list_models provides model information. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern (edit_image, generate_image, list_models) using snake_case, making the set predictable and readable.
With only 3 tools, the set is slightly underpopulated but reasonable for a focused image generation/editing server. The scope is narrow enough that each tool earns its place.
Core operations (generate, edit/fuse, list models) are covered. Minor gaps like delete or get metadata exist, but the surface is functional for the primary use cases.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Generate and edit images and create short videos inside Claude. Prepaid credits, no subscription.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Turn Claude into a creative studio: DNA-locked characters, images, video, voiceover — 55 tools.
Multiple Google accounts (Gmail, Calendar, Drive, Contacts, Tasks) in one Claude connector.
