# gemini-image [Health: Active]

**Category:** 🎨 Art & Culture  
**Repository:** https://github.com/JimothySnicket/gemini-image-mcp  
**GitHub Stars:** 1  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/gemini-image

## Description
Google Gemini image generation, editing, and local processing via MCP

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "gemini-image": {
    "command": "npx",
    "args": ["-y","@jimothy-snicket/gemini-image-mcp"],
    "env": {
      "GEMINI_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `GEMINI_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/gemini-image/readme_