Gemini 2.5 Flash Image MCP Server

How to use

You use this server by connecting it to an MCP client. Once connected, you can generate images from detailed prompts, edit images with simple language, and blend or transfer styles between images. The server runs locally or remotely via an MCP transport, and you supply your Gemini API key to authorize requests.

Common workflows include: creating a brand-new image from a detailed prompt, refining an existing image by requesting edits, combining elements from multiple images into a single composition, and applying a chosen style from one image to another. You can also choose to receive a base64 image in the response and optionally save it to a file.

How to install

Prerequisites you need before installing this server:

- Node.js 18 or newer

- An MCP client to connect to the server (examples include Claude Code, Cursor, VS Code, Windsurf, etc.)

- Gemini API key set as an environment variable GEMINI_API_KEY before starting the server

Install and run the server with the standard configuration. The following steps show a straightforward setup using the npm/npx approach.

# 1) Create a minimal MCP config file with the standard stdio setup
# This config runs the MCP server via npx and the Gemini MCP package
cat > mcpconfig.json << 'JSON'
{
  "mcpServers": {
    "gemini-2-5-flash-mcp": {
      "command": "npx",
      "args": ["@taiyokimura/gemini-2-5-flash-mcp@latest"]
    }
  }
}
JSON

# 2) Install dependencies (local development flow)
npm install

# 3) Start the MCP server (run after installation)
npx @taiyokimura/gemini-2-5-flash-mcp@latest

# 4) Alternatively, run a global install and register with your MCP client
npm i -g @taiyokimura/gemini-2-5-flash-mcp
# Then you can reference the global binary in your MCP client setup

# 5) Ensure GEMINI_API_KEY is set in your environment when starting the server
export GEMINI_API_KEY="YOUR_API_KEY"

Additional configuration and environment

Environment variables you will use:

- GEMINI_API_KEY: Required. Your Google Gemini API key used to access the Gemini 2.5 Flash Image Preview services.

Optional runtime configuration for HTTP transport (experimental) can be enabled to serve MCP over HTTP if your MCP client supports Streamable HTTP. In that mode, you will typically start an HTTP server on a specific port and path, and your client will connect to that endpoint.

The standard MCP configuration file shown above is sufficient for most clients. If you prefer to pass the API key at runtime, you can include it in your client’s startup flags or environment as shown in usage examples.

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

Security and maintenance notes

Keep your Gemini API key secret. Do not commit it to version control or expose it in logs. Rotate keys if you suspect a leak.

Regularly update the MCP server package to pick up security fixes and feature improvements. Use your MCP client to manage server instances and monitor any errors reported by the MCP protocol.

Troubleshooting and tips

If you encounter connection issues, verify that GEMINI_API_KEY is correctly set in the environment where the MCP server runs. Confirm the MCP client is configured to point to your server using the canonical server name gemini-2-5-flash-mcp.

When using image generation or editing features, ensure your prompts are detailed enough for Gemini 2.5 to produce expected results. If an operation times out, consider increasing any client-side timeouts or retrying with slightly adjusted prompts.

Tools and capabilities

The server provides four core tools to interact with Gemini 2.5 Flash Image Preview:

- generate_image: Create an image from a detailed text prompt, with an optional saveToFilePath to write the result to disk.

- edit_image: Modify an existing image using a prompt, with an image input and an optional saveToFilePath.

- compose_images: Blend elements from multiple images guided by a prompt, with an optional saveToFilePath.

- style_transfer: Apply the style of one image to another image, with an optional saveToFilePath.

Development

To develop and test locally, you can build and run the project from source. Typical steps include installing dependencies, building the project, and starting the local runtime.

npm install
npm run build
npx .

generate_image

Generate an image from a text prompt and optionally save it to a file path provided by saveToFilePath.

edit_image

Edit an existing image using a prompt and the provided image input, with an optional save-to-file path.

compose_images

Combine elements from multiple images guided by a prompt, with an optional save-to-file path.

style_transfer

Transfer the style from one image to another image, with an optional save-to-file path.