{
  "markdown": "# gemini-image-studio-mcp\n\nMCP 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.\n\n[![npm version](https://img.shields.io/npm/v/gemini-image-studio-mcp.svg)](https://www.npmjs.com/package/gemini-image-studio-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## What Makes This Different\n\nMost Gemini image MCP servers are basic text-to-image wrappers. This one adds a **structured editing pipeline**:\n\n1. **Generate** an image from text or JSON prompts\n2. **Decompose** it into a structured JSON blueprint (every visual component mapped)\n3. **Edit** by changing specific fields — `subject[0].hair.color: \"platinum_blonde\"` — and regenerating\n\nThis 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.\n\n## Features\n\n- **5 MCP Tools** — generate, decompose, edit, presets, list\n- **Structured JSON Editing** — decompose images into blueprints, edit specific fields with dot-notation\n- **Natural Language Editing** — or just describe the change in plain English\n- **10 Built-in Presets** — Facebook ads, Instagram stories, hero images, OG images, YouTube thumbnails, and more\n- **Reference Image Support** — up to 14 reference images for character/object consistency\n- **Dual Model Support** — Gemini 3.1 Flash (fast) or Gemini 3 Pro (best quality)\n- **Blueprint Caching** — decomposed blueprints cached alongside images for instant re-edits\n- **Google Search Grounding** — real-world accuracy via web search\n- **Smart Error Handling** — retry on rate limits, clear safety block messages, file size warnings\n\n## Quick Start\n\n### 1. Get a Gemini API Key\n\nGet one free at [Google AI Studio](https://aistudio.google.com/apikey).\n\n### 2. Install\n\n```bash\nnpm install -g gemini-image-studio-mcp\n```\n\n### 3. Add to Claude Code\n\n```bash\nclaude mcp add gemini-image-studio-mcp -e GEMINI_API_KEY=your-key-here -- gemini-image-studio-mcp\n```\n\nOr add to your project's `.claude/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gemini-image-studio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"gemini-image-studio-mcp\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-key-here\"\n      }\n    }\n  }\n}\n```\n\n### 4. Use It\n\nAsk Claude to generate images:\n\n> \"Create a Facebook ad for a coffee shop with warm lighting\"\n\n> \"Generate a hero image for a tech startup landing page\"\n\n> \"Edit the hero image — change the background to a sunset beach\"\n\n## Tools\n\n### `generate_image`\n\nCreate a new image from text or structured JSON prompts.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `prompt` | string | Yes | Text description or JSON prompt |\n| `prompt_format` | `\"text\"` \\| `\"json\"` | No | Prompt format (default: `\"text\"`) |\n| `preset` | string | No | Asset preset (e.g., `\"facebook_ad\"`, `\"hero_image\"`) |\n| `aspect_ratio` | string | No | Override ratio (`\"1:1\"`, `\"16:9\"`, `\"9:16\"`, etc.) |\n| `image_size` | `\"1K\"` \\| `\"2K\"` \\| `\"4K\"` | No | Resolution (default: `\"1K\"`) |\n| `model` | `\"flash\"` \\| `\"pro\"` | No | Gemini model (default: `\"flash\"`) |\n| `reference_images` | string[] | No | Paths to reference images for consistency |\n| `output_name` | string | No | Custom filename |\n| `enable_search_grounding` | boolean | No | Use Google Search for accuracy |\n\n### `decompose_image`\n\nAnalyze an image into a structured JSON blueprint — the first step of the edit workflow.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `image_path` | string | Yes | Path to the image |\n| `detail_level` | `\"basic\"` \\| `\"detailed\"` \\| `\"exhaustive\"` | No | Granularity (default: `\"detailed\"`) |\n\nReturns a full blueprint with `subject`, `scene`, `technical`, `composition`, `text_rendering`, `style_modifiers`, and `meta` sections — each field precisely describing the image's visual components.\n\n### `edit_image`\n\nEdit an image using JSON changes or natural language.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `image_path` | string | Yes | Path to the image |\n| `edit_type` | `\"json\"` \\| `\"natural_language\"` | Yes | Edit mode |\n| `changes` | object | For JSON edits | Dot-notation paths to change |\n| `instruction` | string | For NL edits | Natural language instruction |\n| `blueprint` | object | No | Blueprint (auto-loaded from cache if omitted) |\n| `model` | `\"flash\"` \\| `\"pro\"` | No | Model (default: `\"flash\"`) |\n| `output_name` | string | No | Custom filename |\n\n**JSON edit example** — change hair color and add sunglasses:\n```json\n{\n  \"image_path\": \"/output/portrait.png\",\n  \"edit_type\": \"json\",\n  \"changes\": {\n    \"subject[0].hair.color\": \"platinum_blonde\",\n    \"subject[0].accessories\": [\n      { \"item\": \"sunglasses\", \"material\": \"metal\", \"color\": \"#C0C0C0\" }\n    ]\n  }\n}\n```\n\n**Natural language edit example:**\n```json\n{\n  \"image_path\": \"/output/portrait.png\",\n  \"edit_type\": \"natural_language\",\n  \"instruction\": \"Change the background to a tropical beach at sunset. Keep the person exactly the same.\"\n}\n```\n\n### `get_presets`\n\nList available asset presets with dimensions, tips, and conventions.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `category` | `\"ad\"` \\| `\"web\"` \\| `\"social\"` \\| `\"all\"` | No | Filter (default: `\"all\"`) |\n\n### `list_generated`\n\nBrowse previously generated images.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `filter` | string | No | Search by filename |\n| `limit` | number | No | Max results (default: 20) |\n| `include_blueprints` | boolean | No | Include cached blueprints |\n\n## JSON Editing Workflow\n\nThe key differentiator — precise, field-level image editing:\n\n```\nStep 1: Generate\n  generate_image(prompt: \"Professional headshot, navy blazer\", preset: \"linkedin_post\")\n  → /output/headshot.png\n\nStep 2: Decompose\n  decompose_image(image_path: \"/output/headshot.png\")\n  → JSON blueprint with every visual component mapped\n\nStep 3: Edit (precise)\n  edit_image(\n    image_path: \"/output/headshot.png\",\n    edit_type: \"json\",\n    changes: {\n      \"subject[0].clothing[0].color\": \"#8B0000\",\n      \"scene.lighting.type\": \"studio_softbox\"\n    }\n  )\n  → /output/headshot-edit-1.png (blazer changed to dark red, lighting adjusted)\n\nStep 4: Edit (creative)\n  edit_image(\n    image_path: \"/output/headshot-edit-1.png\",\n    edit_type: \"natural_language\",\n    instruction: \"Add warm bokeh to the background\"\n  )\n  → /output/headshot-edit-1-edit-1.png\n```\n\n### Dot-Notation Paths\n\n```\nsubject[0].hair.color          → Hair color\nsubject[0].hair.style          → Hair style\nsubject[0].clothing[0].color   → First clothing item color\nsubject[0].accessories         → Add/change accessories\nscene.lighting.type            → Lighting type\nscene.location                 → Location/background\ntext_rendering.text_content    → Text in image\ntechnical.lens                 → Camera lens\ncomposition.framing            → Shot framing\nstyle_modifiers.aesthetic      → Aesthetic style\n```\n\n## Built-in Presets\n\n| Preset | Category | Aspect Ratio | Dimensions | Best For |\n|--------|----------|-------------|------------|----------|\n| `facebook_ad` | Ad | 1:1 | 1080x1080 | Facebook/Instagram feed ads |\n| `instagram_story_ad` | Ad | 9:16 | 1080x1920 | Instagram/Facebook story ads |\n| `google_display_banner` | Ad | 16:9 | 1200x628 | Google Display Network |\n| `hero_image` | Web | 21:9 | 2560x1080 | Above-the-fold hero sections |\n| `og_image` | Web | 16:9 | 1200x630 | Social share / link previews |\n| `product_card` | Web | 4:5 | 800x1000 | E-commerce product grids |\n| `email_header` | Web | 3:1 | 600x200 | Email marketing headers |\n| `linkedin_post` | Social | 1:1 | 1080x1080 | LinkedIn feed posts |\n| `twitter_post` | Social | 16:9 | 1200x675 | Twitter/X posts |\n| `youtube_thumbnail` | Social | 16:9 | 1280x720 | YouTube thumbnails |\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `GEMINI_API_KEY` | Yes | — | [Google AI Studio](https://aistudio.google.com/apikey) API key |\n| `OUTPUT_DIR` | No | `./output` | Where generated images are saved |\n\n## Integration\n\n### Claude Code\n\n```bash\nclaude mcp add gemini-image-studio-mcp -e GEMINI_API_KEY=your-key -- gemini-image-studio-mcp\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gemini-image-studio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"gemini-image-studio-mcp\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-key-here\"\n      }\n    }\n  }\n}\n```\n\n### Any MCP Client\n\n```bash\nGEMINI_API_KEY=your-key npx gemini-image-studio-mcp\n```\n\nThe server communicates over stdio using the [Model Context Protocol](https://modelcontextprotocol.io/).\n\n## MCP Prompt & Resource\n\nThis server also exposes:\n\n- **Prompt: `nano_banana_expert`** — invoke this to give Claude full knowledge of the JSON schema, editing best practices, and asset creation guidelines\n- **Resource: `nanobanana://schema/prompt`** — the raw JSON schema with all enum values for programmatic access\n\n## Models\n\n| Model | ID | Best For |\n|-------|------|----------|\n| Flash (default) | `gemini-3.1-flash-image-preview` | Fast generation, high volume, cost-effective |\n| Pro | `gemini-3-pro-image-preview` | Best quality, complex scenes, professional assets |\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/my-feature`)\n3. Run tests (`npm test`)\n4. Commit your changes\n5. Push and open a PR\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 9810,
  "sha": "b7e849adedecdcf89142f84ccdbf36aefba00be7d6875fbe095a6c5624b434d8",
  "repo_slug": "udhaykumarbala/gemini-image-studio-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_udhaykumarbala_gemini_image_st_5c329640/readme"
}