Gemini 2.5 Flash Image MCP

🚀 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. It's designed to be easily installed and used from Claude Code and other MCP clients.

🚀 Quick Start

First, install the MCP server with your client. The following examples focus 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 (with non-interactive flag) + specify API key simultaneously (Claude's -e option)
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

# Global installation + specify API key simultaneously (Claude's -e option)
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

# Registration in HTTP mode (SSE default) example (only for compatible clients)
# ※ In HTTP mode, this process itself runs as an HTTP server.
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 (Experimental)

You can also use Streamable HTTP instead of STDIO. Use it only if your MCP client supports Streamable HTTP.

1. Start the server in HTTP mode

export MCP_TRANSPORT=http
export GEMINI_API_KEY=YOUR_API_KEY
# Optional (default: 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

2. Client-side configuration (example: Streamable HTTP-compatible client)

• Type: HTTP (Streamable)
• URL: http://localhost:7801/mcp

Note:

• SSE streaming is the default. If you want to use JSON responses, set MCP_HTTP_ENABLE_JSON=true.
• Sessions are generated on the server side (stateful). If you want to make it completely stateless, you can change sessionIdGenerator: undefined in the code.

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

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

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

{
  "$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
    }
  }
}

✨ 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

📦 Installation

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"

💻 Usage Examples

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)

🔧 Technical Details

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)

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:

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.

📚 Documentation

References

• MCP SDK: https://modelcontextprotocol.io/docs/sdks
• Architecture: https://modelcontextprotocol.io/docs/learn/architecture
• Server concepts: https://modelcontextprotocol.io/docs/learn/server-concepts
• Server spec (2025-06-18): https://modelcontextprotocol.io/specification/2025-06-18/server/index
• Gemini image generation: https://ai.google.dev/gemini-api/docs/image-generation