Skip to main content
Glama

agileimagegen-mcp

Thin MCP server for Gemini image generation and image editing using a Google AI Studio API key.

This project is designed for fast AI-assisted iteration. For repo-specific guidance, see AGENTS.md, PROJECT_STATE.md, and ARCHITECTURE.md.

What It Does

  • Exposes exactly 2 MCP tools: image.generate and image.edit

  • Uses @google/genai with GOOGLE_API_KEY

  • Runs as a local stdio MCP server

  • Can also run from Docker with the same env contract

  • Saves generated images to disk and returns structured metadata

  • Supports reference-guided generation with anchor images

  • Uses a shared transparency pipeline across generate and edit

Related MCP server: nano-banana-mcpv2

Requirements

  • Node.js 20+

  • A Google AI Studio API key with access to Gemini image-capable models

Environment

Copy .env.example to .env and fill in your key:

GOOGLE_API_KEY=your-google-ai-studio-api-key
AGILEIMAGEGEN_DEFAULT_MODEL=gemini-2.5-flash-image
AGILEIMAGEGEN_OUTPUT_DIR=./output
AGILEIMAGEGEN_LOG_LEVEL=info
AGILEIMAGEGEN_SAVE_PROMPTS=false

Notes:

  • GOOGLE_API_KEY is required.

  • AGILEIMAGEGEN_DEFAULT_MODEL can be overridden per tool call.

  • AGILEIMAGEGEN_OUTPUT_DIR is where generated images are written by default.

  • .env is gitignored and should stay local.

Local Development

Install dependencies:

cmd /c npm install

Run in dev mode:

cmd /c npm run dev

Build:

cmd /c npm run build

Run the built server:

cmd /c npm start

Run tests:

cmd /c npm test

Run live smoke tests:

cmd /c npm run smoke:generate
cmd /c npm run smoke:edit

Docker

Build:

docker build -t agileimagegen-mcp .

Run:

docker run --rm -i --env-file .env -v "${PWD}/output:/app/output" agileimagegen-mcp

The container expects to run as a stdio MCP server, so use -i and wire it through your MCP client.

MCP Client Example

Example local stdio MCP config:

{
  "mcpServers": {
    "agileimagegen": {
      "command": "node",
      "args": ["C:/git/agileimagegen-mcp/dist/server.js"],
      "cwd": "C:/git/agileimagegen-mcp",
      "env": {
        "GOOGLE_API_KEY": "your-key-here"
      }
    }
  }
}

If you prefer .env, keep the cwd pointed at this repo so the server can load it locally.

Tools

image.generate

Input:

{
  "prompt": "Arcade grime sewer cartoon logo",
  "model": "gemini-2.5-flash-image",
  "reference_image_paths": ["C:/temp/input/anchor-logo.png"],
  "size": "square",
  "background": "transparent",
  "transparency_mode": "repair",
  "transparency_threshold": "balanced",
  "filename_hint": "sewer-logo",
  "output_dir": "C:/temp/output"
}

Supported size inputs:

  • preset: square, landscape, portrait, widescreen

  • explicit: WIDTHxHEIGHT

  • or width + height

Transparency controls:

  • transparency_mode: off, validate, or repair

  • transparency_threshold: balanced or strict

Reference guidance:

  • reference_image_paths: optional local anchor images used to steer image.generate

  • when present, generate requests are sent as multimodal requests instead of text-only prompts

Defaults:

  • background: "transparent" implies transparency_mode: "repair"

  • otherwise transparency handling defaults to off

  • transparent workflows prefer a chroma-key background color of #01FF01, but can also accept good native alpha or infer and remove a different solid border color when the provider drifts

  • image.edit and image.generate both run through the same transparency validation/extraction pipeline

image.edit

Input:

{
  "prompt": "Make this sign grimier and add a toxic green edge glow",
  "input_image_paths": ["C:/temp/input/sign.png"],
  "model": "gemini-2.5-flash-image",
  "transparency_mode": "repair",
  "transparency_threshold": "balanced",
  "filename_hint": "sign-edit",
  "output_dir": "C:/temp/output"
}

For image.edit, transparency repair runs by default when the prompt implies transparent or alpha output.

Tool Output Shape

Both tools return structured content in this shape:

{
  "path": "C:/git/agileimagegen-mcp/output/123456-sewer-logo.png",
  "mime_type": "image/png",
  "model": "gemini-2.5-flash-image",
  "provider": "google",
  "prompt_summary": "Arcade grime sewer cartoon logo",
  "warnings": [],
  "width": 1024,
  "height": 1024,
  "transparency": {
    "requested": true,
    "mode": "repair",
    "threshold": "balanced",
    "source_mime_type": "image/jpeg",
    "has_alpha": true,
    "alpha_pixel_ratio": 0.44,
    "fully_transparent_ratio": 0.39,
    "opaque_border_ratio": 0.02,
    "checkerboard_detected": false,
    "key_color": "#01FF01",
    "key_color_match_ratio": 0.91,
    "background_mode": "keyed",
    "repair_attempted": true,
    "repair_succeeded": true,
    "warnings": []
  }
}

Design Notes

  • Width, height, size, and transparent background are passed as prompt guidance because Gemini image-capable models may not honor them as hard output controls in all cases.

  • When transparency is requested, the server uses a tiered strategy: accept usable native alpha first, otherwise prefer the requested #01FF01 chroma-key background, then fall back to inferring and removing a different solid border color.

  • Provider-native transparency is still validated before use; opaque outputs are converted to transparency only when the background is cleanly separable.

  • Transparency diagnostics are returned to the caller so layered asset workflows can reason about confidence, repair attempts, and failure modes.

  • Prompt specialization is intentionally out of scope for this repo. Project-specific prompt rules should live in the caller’s skill/workflow layer.

  • Error messages are sanitized so normal failures do not leak raw API keys.

Available Tools

2 tools
image.editA

Edit one or more local images with Gemini using multimodal input. Saves the result to disk and returns structured metadata.

Inputs: prompt (required), input_image_paths (required), model, output_dir, +3 more. Returns: path, model, width, height, +5 more

image.generateA

Generate an image with Gemini using a Google AI Studio API key. Saves the result to disk and returns structured metadata.

Inputs: prompt (required), size, model, width, +7 more. Returns: path, model, width, height, +5 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools, image.generate and image.edit, are clearly distinct: one creates a new image and the other modifies existing images. There is no overlap in their purposes, making it easy for an agent to select the correct tool.

    Naming Consistency5/5

    Both tool names follow a consistent image.<verb> pattern (generate, edit). The uniform use of the dot separator and the shared namespace creates a predictable naming convention.

    Tool Count3/5

    With only 2 tools, the server feels thin. While both tools serve a clear purpose, the count is borderline and does not provide a broader toolkit that might be expected from an image-focused server.

    Completeness4/5

    The server covers the core operations of generating and editing images, which are its stated purpose. There are no obvious missing operations within that narrow scope, though it lacks any lifecycle management (e.g., listing or deleting images).

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers