gemini-image-studio-mcp

MCP server for AI image generation and editing with Google Gemini. Create web assets, ad creatives, and brand visuals — with structured JSON editing for precise, repeatable control.

What Makes This Different

Most Gemini image MCP servers are basic text-to-image wrappers. This one adds a structured editing pipeline:

1. Generate an image from text or JSON prompts
2. Decompose it into a structured JSON blueprint (every visual component mapped)
3. Edit by changing specific fields — subject[0].hair.color: "platinum_blonde" — and regenerating

This means precise, isolated changes without affecting the rest of the image. Change a hair color without touching the background. Swap clothing without altering the pose. All through dot-notation JSON paths.

Features

• 5 MCP Tools — generate, decompose, edit, presets, list
• Structured JSON Editing — decompose images into blueprints, edit specific fields with dot-notation
• Natural Language Editing — or just describe the change in plain English
• 10 Built-in Presets — Facebook ads, Instagram stories, hero images, OG images, YouTube thumbnails, and more
• Reference Image Support — up to 14 reference images for character/object consistency
• Dual Model Support — Gemini 3.1 Flash (fast) or Gemini 3 Pro (best quality)
• Blueprint Caching — decomposed blueprints cached alongside images for instant re-edits
• Google Search Grounding — real-world accuracy via web search
• Smart Error Handling — retry on rate limits, clear safety block messages, file size warnings

Quick Start

1. Get a Gemini API Key

Get one free at Google AI Studio.

2. Install

npm install -g gemini-image-studio-mcp

3. Add to Claude Code

claude mcp add gemini-image-studio-mcp -e GEMINI_API_KEY=your-key-here -- gemini-image-studio-mcp

Or add to your project's .claude/mcp.json:

{
  "mcpServers": {
    "gemini-image-studio-mcp": {
      "command": "npx",
      "args": ["-y", "gemini-image-studio-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

4. Use It

Ask Claude to generate images:

"Create a Facebook ad for a coffee shop with warm lighting"

"Generate a hero image for a tech startup landing page"

"Edit the hero image — change the background to a sunset beach"

Tools

generate_image

Create a new image from text or structured JSON prompts.

decompose_image

Analyze an image into a structured JSON blueprint — the first step of the edit workflow.

Returns a full blueprint with subject, scene, technical, composition, text_rendering, `s

... View full README on GitHub