agileimagegen-mcp
Provides tools for generating and editing images using Google's Gemini models via a Google AI Studio API key.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agileimagegen-mcp Generate a cartoon robot holding a wrench"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.generateandimage.editUses
@google/genaiwithGOOGLE_API_KEYRuns as a local
stdioMCP serverCan 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=falseNotes:
GOOGLE_API_KEYis required.AGILEIMAGEGEN_DEFAULT_MODELcan be overridden per tool call.AGILEIMAGEGEN_OUTPUT_DIRis where generated images are written by default..envis gitignored and should stay local.
Local Development
Install dependencies:
cmd /c npm installRun in dev mode:
cmd /c npm run devBuild:
cmd /c npm run buildRun the built server:
cmd /c npm startRun tests:
cmd /c npm testRun live smoke tests:
cmd /c npm run smoke:generate
cmd /c npm run smoke:editDocker
Build:
docker build -t agileimagegen-mcp .Run:
docker run --rm -i --env-file .env -v "${PWD}/output:/app/output" agileimagegen-mcpThe 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,widescreenexplicit:
WIDTHxHEIGHTor
width+height
Transparency controls:
transparency_mode:off,validate, orrepairtransparency_threshold:balancedorstrict
Reference guidance:
reference_image_paths: optional local anchor images used to steerimage.generatewhen present, generate requests are sent as multimodal requests instead of text-only prompts
Defaults:
background: "transparent"impliestransparency_mode: "repair"otherwise transparency handling defaults to
offtransparent 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 driftsimage.editandimage.generateboth 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
#01FF01chroma-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 toolsimage.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
Scored across 2 tools
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.
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.
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.
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
Related MCP Connectors
Generate and edit images (PNG, transparent, GIF, SVG) with GPT Image and Nano Banana models.
Generate, edit and upscale images with references, batch jobs, cost previews and original downloads.
Commercially licensed image generation and editing with IP indemnification.
Image generation, image editing and text/image-to-video with credit quotes and connection budgets.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables image generation and editing using Google's Gemini models with support for model selection and custom aspect ratios. Users can generate high-quality images or modify existing ones through natural language prompts while controlling specific parameters like quality and dimensions.-
- AlicenseAqualityCmaintenanceEnables AI image generation and editing using Google's Gemini Multimodal Image APIs.61MIT
- FlicenseNot gradedqualityDmaintenanceEnables image generation using Google Gemini models (flash/pro) with support for multiple sizes, reference images, and access control via Google OAuth and email allow-lists.1-
- AlicenseAqualityCmaintenanceEnables AI image generation and editing using Google's Gemini models via natural language, supporting multi-turn editing, search grounding, storyboards, icon sets, and video-to-image.511 npm1MIT