playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

Gemini 2.5 Flash Image MCP server

Integrates with Google Gemini 2.5 Flash to provide text-to-image generation, image editing, composition, and style transfer capabilities with support for base64 and file path inputs.
Back to servers
Setup instructions
Provider
nanameru
Release date
Aug 28, 2025
Language
Go
Stats
1 star
View on GitHub

The Gemini 2.5 Flash Image MCP server provides a convenient way to generate and edit images using Google's Gemini 2.5 Flash Image model through the Model Context Protocol (MCP). It enables text-to-image generation, image editing, multi-image composition, and style transfer from any MCP-compatible client.

Requirements

  • Node.js 18 or newer
  • An MCP client (Claude Code, Cursor, VS Code, Windsurf, etc.)
  • Google Gemini API Key

Getting a Gemini API Key

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 when running the server
# macOS / Linux (bash/zsh)
export GEMINI_API_KEY="YOUR_API_KEY"

# Windows PowerShell
$env:GEMINI_API_KEY="YOUR_API_KEY"

Installation

The standard configuration works in most MCP clients:

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

Quick Installation with Claude Code

# Using npx with API key
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

# Using global installation
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 mode registration (for supported clients)
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

HTTP Mode (Experimental)

You can use Streamable HTTP instead of STDIO if your MCP client supports it:

  1. Start the server in HTTP mode:
export MCP_TRANSPORT=http
export GEMINI_API_KEY=YOUR_API_KEY
# Optional settings (defaults: 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. Configure your client:
    • Type: HTTP (Streamable)
    • URL: http://localhost:7801/mcp

Client-Specific Installation

Claude Code (Recommended)

# 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

Cursor

  1. Go to Cursor Settings → MCP → Add new MCP Server
  2. Configure:
    • Name: gemini-2-5-flash-mcp
    • Type: command
    • Command: npx
    • Args: @taiyokimura/gemini-2-5-flash-mcp@latest
    • Auto start: on (optional)

VS Code

Add via CLI:

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

LM Studio

Add MCP Server with:

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

Goose

Advanced settings → Extensions → Add custom extension:

  • Type: STDIO
  • Command: npx
  • Args: @taiyokimura/gemini-2-5-flash-mcp@latest
  • Enabled: true

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

Generate Image

Generate an image from a text prompt.

Parameters:

  • prompt (required): Detailed description to generate
  • saveToFilePath (optional): Path to save the image

Example:

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

Edit Image

Edit an image using a prompt.

Parameters:

  • prompt (required): Edit instruction
  • image (required): { dataBase64?: string, path?: string, mimeType?: string }
  • saveToFilePath (optional)

Example:

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

Compose Images

Combine elements from multiple images.

Parameters:

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

Style Transfer

Transfer the style of one image to another.

Parameters:

  • prompt (optional)
  • baseImage (required)
  • styleImage (required)
  • saveToFilePath (optional)

Troubleshooting

For consistent operation, always use the canonical ID gemini-2-5-flash-mcp for identifiers and keys. If you encounter conflicts, remove any old entries (like "GeminiFlash") and re-add with the correct name.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later