Gemini Image

What gemini-image MCP server does

The gemini-image MCP server connects MCP clients to Google Gemini's native image-generation models through the generateContent API. It provides two tools: generate_image for remote Gemini operations and process_image for local transformations. Generated images are saved to disk, so an agent can work with file paths rather than streaming image data through its context.

generate_image supports text-to-image requests, editing with reference images, multi-turn refinement through session IDs, configurable aspect ratios and resolutions, integer seeds, and optional Google Search grounding on supported Gemini 3.x image models. It can accept multiple reference images, with the README documenting approximate limits for specific models. Responses include token counts, estimated cost, and session totals.

The local tool handles crop, resize, background removal, whitespace trimming, and conversion among PNG, JPEG, and WebP. Background removal can use threshold-based processing, chroma keying, or the optional local AI matte workflow. The result can be a transparent PNG without an additional Gemini API call.

How it works

The gemini-image MCP server runs as a local stdio process. MCP clients start the package with npx -y @jimothy-snicket/gemini-image-mcp and provide the Gemini credential through the process environment. Gemini requests use the configured model and write output files to the selected directory. Duplicate names are automatically versioned, and subfolders can organize related outputs.

Multi-turn generation uses a sessionId; earlier turns remain available as context until the configured session timeout. Every generation is also recorded in a generations.jsonl manifest containing the prompt, parameters, and cost information. Request and cost limits can be configured to restrict agent activity over a rolling hour.

Setup and configuration

Install or run the package with npm:

npx -y @jimothy-snicket/gemini-image-mcp

Create a Gemini API key in Google AI Studio and expose it as GEMINI_API_KEY. The same variable can be passed in an MCP client's environment configuration. Claude Code and Claude Desktop examples are provided in the project documentation, and any MCP client supporting stdio transport can launch the process.

Optional configuration can be supplied through environment variables or JSON files. Supported settings include OUTPUT_DIR, DEFAULT_MODEL, LOG_LEVEL, REQUEST_TIMEOUT_MS, MAX_REQUESTS_PER_HOUR, MAX_COST_PER_HOUR, SESSION_TIMEOUT_MS, and GEMINI_IMAGE_AUTO_INSTALL. Configuration precedence is environment variables, project config, global config, then defaults. The --init option creates a documented config file, while --init --local creates a project-specific one.

Tools and capabilities

• Generate images from text prompts.
• Edit images supplied as local reference-file paths.
• Refine images across multi-turn sessions.
• Save outputs with custom names, subfolders, and automatic versioning.
• Crop by pixels, aspect ratio, center, or focal point.
• Resize while maintaining aspect ratio.
• Remove backgrounds with threshold, chroma-key, or optional AI matte processing.
• Trim whitespace and convert between PNG, JPEG, and WebP.
• Set model, aspect ratio, resolution, seed, output location, and request limits.

Limitations and notes

Gemini generation requires GEMINI_API_KEY and may incur API usage costs; the project reports estimates using a built-in pricing table and optional model-specific overrides. Unknown models can still run, but their cost is reported as unknown. The local processing tool does not require API calls.

The default output directory is ~/gemini-images, and the default model is gemini-2.5-flash-image. Supported parameters and aspect ratios depend on the selected Gemini model; for example, some resolutions and very wide or tall ratios are documented as model-specific. Automatic AI matte installation can be disabled with GEMINI_IMAGE_AUTO_INSTALL=0, in which case auto background removal falls back to chroma or threshold processing with instructions.