Skip to main content
Glama
nanameru

Gemini 2.5 Flash Image MCP

by nanameru
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

Gemini 2.5 Flash Image MCP

A Model Context Protocol (MCP) server for conversational image generation and editing with Google's Gemini 2.5 Flash Image Preview. Designed to be easy to install and use from Claude Code and other MCP clients.

Key Features

  • Text-to-Image: Generate images from detailed prompts

  • Image Editing: Edit images with natural language instructions

  • Multi-Image Composition / Style Transfer: Combine images or transfer styles

  • File Save Option: Return base64 image and optionally save to file

  • Provider-Agnostic MCP: Works in any MCP-enabled client

Related MCP server: Nano Banana

Requirements

  • Node.js 18 or newer

  • An MCP client (Claude Code, Cursor, VS Code, Windsurf, etc.)

  • Google Gemini API Key: set GEMINI_API_KEY

Get a Gemini API key

Follow these steps to obtain an API key from Google AI Studio:

  1. Open Google AI Studio and sign in: https://aistudio.google.com/apikey

  2. Click “Create API key” (or “Manage keys” if you already have one)

  3. Copy the generated key

  4. Set it as an environment variable on your machine when running this server

Examples:

# macOS / Linux (bash/zsh)
export GEMINI_API_KEY="YOUR_API_KEY"

# Windows PowerShell
$env:GEMINI_API_KEY="YOUR_API_KEY"

Getting Started

First, install the MCP server with your client. The following examples center on Claude Code usage.

Standard config works in most tools:

{
  "mcpServers": {
    "gemini-2-5-flash-mcp": {
      "command": "npx",
      "args": ["@taiyokimura/gemini-2-5-flash-mcp@latest"]
    }
  }
}

Quick usage (Claude Code)

# npx（非対話フラグ付き） + APIキー同時指定（Claudeの -e 指定）
claude mcp add gemini-2-5-flash-mcp -s user -e GEMINI_API_KEY="YOUR_API_KEY" -- npx -y @taiyokimura/gemini-2-5-flash-mcp@latest

# グローバルインストール + APIキー同時指定（Claudeの -e 指定）
npm i -g @taiyokimura/gemini-2-5-flash-mcp \
  && claude mcp add gemini-2-5-flash-mcp -s user -e GEMINI_API_KEY="YOUR_API_KEY" -- gemini-2-5-flash-mcp

# HTTP モードで登録（SSE既定）例（対応クライアントのみ）
# ※ HTTP モードはこのプロセス自体がHTTPサーバとして常駐します
claude mcp add gemini-2-5-flash-mcp -s user \
  -e GEMINI_API_KEY="YOUR_API_KEY" \
  -e MCP_TRANSPORT="http" \
  -e MCP_HTTP_PORT="7801" \
  -e MCP_HTTP_PATH="/mcp" \
  -- npx -y @taiyokimura/gemini-2-5-flash-mcp@latest

Streamable HTTP mode（実験的）

STDIO の代わりに Streamable HTTP を使うこともできます。MCP クライアントが Streamable HTTP に対応している場合のみ利用してください。

  1. サーバーを HTTP モードで起動

export MCP_TRANSPORT=http
export GEMINI_API_KEY=YOUR_API_KEY
# 任意（既定: 7801, /mcp, SSE）
export MCP_HTTP_PORT=7801
export MCP_HTTP_PATH=/mcp
export MCP_HTTP_ENABLE_JSON=false

npm run build
node ./build/index.js
# => HTTP transport listening on http://localhost:7801/mcp

  1. クライアント側設定（例: Streamable HTTP対応クライアント）

  • Type: HTTP (Streamable)

  • URL: http://localhost:7801/mcp

注:

  • SSE ストリーミングが既定。JSONレスポンスで使いたい場合は MCP_HTTP_ENABLE_JSON=true。

  • セッションはサーバー側で生成（stateful）。完全 stateless にしたい場合はコード側で sessionIdGenerator: undefined に変更可能です。

Use the Claude Code CLI to add the MCP server:

claude mcp add gemini-2-5-flash-mcp -s user -- npx @taiyokimura/gemini-2-5-flash-mcp@latest

Remove if needed:

claude mcp remove gemini-2-5-flash-mcp

Follow the MCP install guide and use the standard config above.

Go to Cursor Settings → MCP → Add new MCP Server.

Use the following:

  • Name: gemini-2-5-flash-mcp

  • Type: command

  • Command: npx

  • Args: @taiyokimura/gemini-2-5-flash-mcp@latest

  • Auto start: on (optional)

Add via CLI:

code --add-mcp '{"name":"gemini-2-5-flash-mcp","command":"npx","args":["@taiyokimura/gemini-2-5-flash-mcp@latest"]}'

Or use the standard config in settings.

Add MCP Server with:

  • Command: npx

  • Args: ["@taiyokimura/gemini-2-5-flash-mcp@latest"]

Advanced settings → Extensions → Add custom extension:

  • Type: STDIO

  • Command: npx

  • Args: @taiyokimura/gemini-2-5-flash-mcp@latest

  • Enabled: true

Example ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gemini-2-5-flash-mcp": {
      "type": "local",
      "command": [
        "npx",
        "@taiyokimura/gemini-2-5-flash-mcp@latest"
      ],
      "enabled": true
    }
  }
}

Open Qodo Gen → Connect more tools → + Add new MCP → Paste the standard config above → Save.

Follow Windsurf MCP documentation and use the standard config above.

Environment Variables

  • GEMINI_API_KEY (required)

  • GEMINI_IMAGE_ENDPOINT (optional) default: https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image-preview:generateContent

  • MCP_NAME (optional, default: gemini-2-5-flash-mcp)

Available Tools

1. generate_image

Generate an image from a text prompt.

Parameters:

  • prompt (required): Detailed description to generate

  • saveToFilePath (optional): Path to save the image

Example input:

{
  "prompt": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
  "saveToFilePath": "./gemini-native-image.png"
}

2. edit_image

Edit an image using a prompt.

Parameters:

  • prompt (required): Edit instruction

  • image (required): { dataBase64?: string, path?: string, mimeType?: string }

  • saveToFilePath (optional)

Example input:

{
  "prompt": "Add a small, knitted wizard hat to the cat",
  "image": { "path": "./cat.jpeg", "mimeType": "image/jpeg" },
  "saveToFilePath": "./gemini-edited-image.png"
}

3. compose_images

Combine elements from multiple images.

Parameters:

  • prompt (required)

  • images (required): Array of image inputs (2-3 recommended)

  • saveToFilePath (optional)

4. style_transfer

Transfer the style of one image to another.

Parameters:

  • prompt (optional)

  • baseImage (required)

  • styleImage (required)

  • saveToFilePath (optional)

Development

Run locally:

npm install
npm run build
npx .

Name Consistency & Troubleshooting

  • Always use CANONICAL_ID (gemini-2-5-flash-mcp) for identifiers and keys.

  • Use CANONICAL_DISPLAY (Gemini 2.5 Flash MCP) only for UI labels.

  • Do not mix different names across clients.

Consistency Matrix:

  • npm package name → gemini-2-5-flash-mcp

  • Binary name → gemini-2-5-flash-mcp

  • MCP server name (SDK metadata) → gemini-2-5-flash-mcp

  • Env default MCP_NAME → gemini-2-5-flash-mcp

  • Client registry key → gemini-2-5-flash-mcp

  • UI label → Gemini 2.5 Flash MCP

Conflict Cleanup:

  • Remove any old entries like "GeminiFlash" and re-add with gemini-2-5-flash-mcp.

  • Ensure global registries only use gemini-2-5-flash-mcp for keys.

  • Cursor: configure in the UI only. This project does not include .cursor/mcp.json.

References

Available Tools

4 tools
compose_imagesC

Compose a new image using multiple input images and a guiding prompt.

ParametersJSON Schema
NameRequiredDescriptionDefault
imagesYes
promptYesDescribe how to compose the elements of the input images.
saveToFilePathNoOptional path to save the composed image

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool composes a new image but doesn't cover critical aspects like whether this is a read-only or destructive operation, authentication needs, rate limits, or what the output looks like (e.g., format, size). For a tool with no annotations and an implied mutation (creating a new image), this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part ('Compose a new image,' 'using multiple input images,' 'and a guiding prompt') contributes directly to understanding the tool's function, making it appropriately concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of an image composition tool with no annotations, no output schema, and incomplete parameter documentation (67% coverage), the description is inadequate. It doesn't address behavioral traits, output details, or usage guidelines, leaving significant gaps for the agent to infer how and when to use this tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67% (2 out of 3 parameters have descriptions). The description adds minimal value beyond the schema: it mentions 'multiple input images' (implied by the 'images' array with minItems:2) and 'guiding prompt' (matching the 'prompt' parameter). It doesn't explain the 'saveToFilePath' parameter or provide additional context like image format constraints. With moderate schema coverage, the baseline of 3 is appropriate as the description doesn't significantly compensate for gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Compose a new image using multiple input images and a guiding prompt.' It specifies the verb ('compose'), resource ('new image'), and key inputs (multiple images + prompt). However, it doesn't explicitly differentiate from siblings like 'edit_image' or 'generate_image' beyond mentioning 'multiple input images,' which might be insufficient for clear sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'edit_image' or 'generate_image,' nor does it specify prerequisites such as needing at least two images. Without any when-to-use or when-not-to-use context, the agent lacks direction for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

edit_imageC

Edit an image using a prompt. Provide one input image via base64 or file path.

ParametersJSON Schema
NameRequiredDescriptionDefault
imageYesOne input image
promptYesDescribe the edit; the model matches original style and lighting.
saveToFilePathNoOptional path to save the edited image

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool edits an image but doesn't mention side effects (e.g., whether it modifies the original file or creates a new one), permissions needed, rate limits, or output format. The mention of 'saveToFilePath' hints at file creation, but this is insufficient for a mutation tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—two sentences that directly state the tool's function and input requirements without any fluff. It's front-loaded with the core purpose, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., file handling, error cases), doesn't explain the return value or output format, and provides minimal guidance on usage. Given the complexity of image editing, this leaves significant gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents parameters. The description adds minimal value by reiterating 'one input image via base64 or file path,' which is already clear in the schema. It doesn't explain the 'prompt' parameter's role beyond 'Describe the edit,' leaving the agent to rely on the schema's more detailed description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Edit an image') and the mechanism ('using a prompt'), which distinguishes it from sibling tools like 'generate_image' (creation) and 'style_transfer' (style application). However, it doesn't specify what types of edits are possible beyond 'using a prompt,' making it slightly less specific than a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'compose_images' or 'style_transfer.' It mentions providing 'one input image,' but doesn't clarify use cases, prerequisites, or exclusions, leaving the agent to infer usage from tool names alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_imageC

Generate an image from a text prompt using Gemini 2.5 Flash Image

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesDetailed scene description. Use photographic terms for photorealism.
saveToFilePathNoOptional path to save the image (png/jpeg by extension)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the method ('using Gemini 2.5 Flash Image') but doesn't cover key traits like rate limits, authentication needs, output format, error handling, or whether it's a read/write operation. For a generative tool with zero annotation coverage, this leaves critical behavioral aspects unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without any fluff or redundancy. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly. Every word earns its place, contributing to clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of an image generation tool, lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., image data, file path, errors), behavioral aspects like costs or limitations, or how it differs from siblings. This leaves significant gaps for an agent to understand the tool fully.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters ('prompt' and 'saveToFilePath') with descriptions. The tool description adds no additional parameter semantics beyond what's in the schema, such as examples or constraints. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Generate an image from a text prompt using Gemini 2.5 Flash Image'. It specifies the verb ('generate'), resource ('image'), and method ('from a text prompt'), but doesn't explicitly differentiate from sibling tools like 'compose_images' or 'edit_image', which might also generate or modify images. This makes it clear but not fully sibling-distinctive.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'compose_images', 'edit_image', or 'style_transfer'. It doesn't mention any prerequisites, exclusions, or specific contexts for usage, leaving the agent to infer based on tool names alone. This lack of explicit guidance is a significant gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

style_transferB

Transfer style from a style image to a base image, guided by an optional prompt.

ParametersJSON Schema
NameRequiredDescriptionDefault
baseImageYes
promptNoOptional additional instruction for the style transfer.
saveToFilePathNoOptional path to save the output
styleImageYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that style is transferred, but omits important details such as potential image size/resolution constraints, output format, and whether the operation is deterministic or requires significant computation. This is insufficient for an AI agent to anticipate side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that efficiently conveys the core function. Every word contributes to understanding, with no unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite moderate complexity (4 parameters, nested images, no output schema), the description fails to provide adequate context. It does not specify the output format (e.g., generated image returned inline or saved to path), behavior when prompt is omitted, or any error conditions. This leaves significant gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50% (prompt and saveToFilePath have descriptions; baseImage and styleImage do not). The tool description adds no additional parameter meaning beyond the schema—it merely restates 'optional prompt'. Given the presence of nested image objects without detailed parameter descriptions, the description should have clarified expected image formats or requirements.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('transfer') and clearly identifies the resources ('style image', 'base image'), making the tool's function unambiguous. It also distinguishes this tool from siblings like 'compose_images' or 'edit_image' by explicitly mentioning style transfer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used for style transfer tasks, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., compose_images, edit_image). No usage restrictions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedcompose_images
    • First observededit_image
    • First observedgenerate_image
    • First observedstyle_transfer
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: compose_images combines multiple images with a prompt, edit_image modifies a single image, generate_image creates from text only, and style_transfer applies artistic style. There is no overlap or ambiguity between these functions.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with snake_case naming: compose_images, edit_image, generate_image, style_transfer. The naming is predictable and readable throughout the set.

Tool Count5/5

With 4 tools, this is well-scoped for an image generation/editing server. Each tool earns its place by covering distinct operations (composition, editing, generation, style transfer) without redundancy or bloat.

Completeness4/5

The toolset covers core image manipulation workflows: generation, editing, composition, and style transfer. A minor gap exists in lacking direct image analysis or metadata tools, but the provided tools allow agents to handle most image-related tasks effectively.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches