Which integrations are available for this server?

Provides tools for generating and editing images using Google's Gemini models via a Google AI Studio API key.

How do I use agileimagegen-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by rbibbey

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

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.

ParametersJSON Schema

Name	Required	Description	Default
`model`	No
`prompt`	Yes
`output_dir`	No
`filename_hint`	No
`input_image_paths`	Yes
`transparency_mode`	No
`transparency_threshold`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`model`	Yes
`width`	No
`height`	No
`provider`	Yes
`warnings`	Yes
`mime_type`	Yes
`transparency`	No
`prompt_summary`	Yes

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavior. It mentions saving results to disk and returning structured metadata, which is more than absent, but it does not disclose whether original files are overwritten, permission requirements, reversibility, or any other side effects beyond saving. This is a moderate level of transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the main purpose, and every word contributes to understanding the tool. There is no verbosity or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the tool has 7 parameters, 2 enum-based, and 2 required. The description does not cover the semantics of these parameters, nor does it mention constraints or usage context. It is too incomplete for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain parameter meanings. It only implicitly refers to prompt and input_image_paths ('Edit one or more local images', 'multimodal input'). No meaning is added for model, output_dir, filename_hint, transparency_mode, or transparency_threshold, leaving most of the 7-parameter schema unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool edits one or more local images using Gemini with multimodal input, and specifies outcomes (saves to disk, returns metadata). The verb 'edit' distinguishes it from the sibling 'image.generate'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the description—use for editing existing local images—but there is no explicit guidance on when to prefer this over alternatives, no prerequisites mentioned (e.g., file existence), and no exclusions or alternative tool references.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

image.generateA

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

ParametersJSON Schema

Name	Required	Description	Default
`size`	No
`model`	No
`width`	No
`height`	No
`prompt`	Yes
`background`	No
`output_dir`	No
`filename_hint`	No
`transparency_mode`	No
`reference_image_paths`	No
`transparency_threshold`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`model`	Yes
`width`	No
`height`	No
`provider`	Yes
`warnings`	Yes
`mime_type`	Yes
`transparency`	No
`prompt_summary`	Yes

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description carries the full burden of disclosing side effects. It transparently states that the tool requires a Google AI Studio API key, saves the result to disk, and returns structured metadata. However, it does not mention potential overwrite behavior, network usage, or error conditions, which would enhance transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at two sentences, front-loaded with the primary action 'Generate an image', and provides key behavioral context (API key, disk save, metadata) without unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 11 parameters, no annotations, and only a minimal description, the context is incomplete. While an output schema exists to explain return values, the description lacks parameter semantics, usage guidance, and deeper behavioral specifics, making it insufficient for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 11 parameters with 0% description coverage, and the tool description does not explain any of them. The description only mentions generating an image and saving to disk, leaving all parameter details ambiguous. This is a significant gap that the description fails to compensate for.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates an image with Gemini, distinguishing it from the sibling image.edit by using the verb 'Generate' versus 'edit'. It also mentions saving to disk and returning metadata, which gives a clear purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for generating new images, but it does not explicitly contrast with the sibling image.edit or provide when-not-to-use guidance. It mentions an API key requirement, which is helpful context, but lacks explicit alternative selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

2 tool updatesv0.1.0Aug 9, 2026
- First observedimage.edit
- First observedimage.generate

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-08-09 17:10 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

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

fengyinxia-jimeng-mcp
ai.smithery
Create images and videos from prompts, with options for image mixing, reference images, and start/…
Image & Video Processing Multimedia Processing
2
img-forge
io.github.Stackbilt-dev
AI image generation across 5 quality tiers (SDXL to Gemini 3 Pro), 50 free credits on signup.
AI & Machine Learning Image & Video Processing
2
Avocado AI
io.github.Wandersonjack
Generate AI images, videos, music, SFX & speech in any AI assistant. Results appear inline in chat.
AI & Machine Learning Image & Video Processing Marketing
2
mcp A
com.budgetpixel
Generate AI images, video, music, and sound effects, and upscale them, from any MCP client.
AI & Machine Learning Image & Video Processing Audio Processing
1312

Related MCP Servers

Nano Banana MCP
Image & Video Processing Multimedia Processing
brandon695
F
license
Not graded
quality
C
maintenance
Enables 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.
Updated 6 months ago (2026-03-08 00:56 UTC)
-
nano-banana-mcpv2
Image & Video Processing AI & Machine Learning
notfixingit3
A
license
A
quality
C
maintenance
Enables AI image generation and editing using Google's Gemini Multimodal Image APIs.
Updated 3 months ago (2026-06-25 00:52 UTC)
6
1
MIT
Image Studio MCP
AI & Machine Learning Image & Video Processing
FloLey
F
license
Not graded
quality
C
maintenance
Enables 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.
Updated 3 months ago (2026-07-01 11:47 UTC)
1
-
nano-banana-mcp
AI & Machine Learning Image & Video Processing
petrkindlmann
A
license
A
quality
D
maintenance
Enables 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.
Updated 3 months ago (2026-06-12 19:53 UTC)
5
8 npm
1
MIT

agileimagegen-mcp

What It Does

Requirements

Environment

Local Development

Docker

MCP Client Example

Tools

image.generate

image.edit

Tool Output Shape

Design Notes

Available Tools

Output Schema

TDQS

Output Schema

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Nano Banana MCP

nano-banana-mcpv2

Image Studio MCP

nano-banana-mcp

`image.generate`

`image.edit`