# gemini-mcp [Health: Active]

**Category:** 🎥 Multimedia Process  
**Repository:** https://github.com/chrischall/gemini-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 4160  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/gemini-mcp-2

## Description
Generate and edit images with Google Gemini (Nano Banana / Nano Banana Pro) image models.

## Tools
Capabilities this server exposes over MCP:

- **gemini_list_models** — List the Gemini image-generation models available to your API key (Nano Banana / Nano Banana Pro family), and the current default model.
- **gemini_healthcheck** — Resolves the credential the way real tools do, then makes one authenticated request to generativelanguage.googleapis.com. Reports which source supplied the credential, whether generativelanguage.googleapis.com accepted it, the round-trip time, and a plain-English hint distinguishing 'no credential' from 'credential rejected' from 'a generativelanguage.googleapis.com-side problem'. Read-only; never returns the credential itself. Call this when a real tool fails and you want to know which hop broke.
- **gemini_image_generate** — Generate image(s) from a text prompt with a Gemini image model (Nano Banana / Nano Banana Pro). If the result will likely be refined iteratively, prefer gemini_interact (multi-turn) as the entry point. Local file inputs are confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
- **gemini_image_edit** — Edit or compose images: provide one or more input images (paths or base64), plus a text instruction. For a SERIES of successive edits to the same image, prefer gemini_interact (multi-turn) — it keeps edit context and avoids re-processing the full image each round; use gemini_image_edit for one-off edits or composing multiple distinct inputs. Gemini over-preserves the input; there is no edit-strength control — for large structural changes, reroll with a different `seed` or more forceful wording. Local file inputs are confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
- **gemini_image_set** — Generate a consistent SET of images: a master image from master_prompt, then one image per scene that references the master so the subject/style stays consistent. Provide `scenes` (explicit per-image prompts) OR `count` (variations of the master). Scene generations run in parallel (reference_mode "master", the default). On the hosted connector: saved `characters` and a saved `style` can seed the whole set by name, multi-image results include a `bundle_url` zip of every image (one curl instead of N), and `max_wait_ms` returns a pollable job handle if the batch runs long. Local file inputs are confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
- **gemini_interact** — Preferred tool for iterative refinement of a single image — multi-turn generation and editing via the Interactions API. To refine, pass the returned interaction `id` as `previous_interaction_id` on the next call; do NOT start a new interaction or re-send the image for each tweak. `continue_last: true` chains from this session's most recent interaction without threading the id. If a call times out client-side the generation usually still completes: the image and an `<image>.json` sidecar holding its interaction id land in the output dir, and `continue_last: true` still resumes it — look there before re-issuing, which bills a second generation. A chained 404 is re-anchored on the prior output and re-issued un-chained (`chain_recovered`); a second 404 means the interaction id was not the cause — check the model id / files uri. Output is JPEG. Local file inputs are confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
- **gemini_video_generate** — Generate a short video (~10s) via the Gemini omni model: text→video, image→video / reference→video (supply reference image[s]), interpolate between two stills (pass first frame then last frame as images), or continue a prior video (task: "edit" or "extend" + previous_interaction_id / continue_last; extensions add ~3-10s each, to ~40s total). Cost scales with `resolution` — draft at 360p, keep at 1080p/4k. Output is written to disk as MP4 (video has no inline MCP block). Video runs long — give it a `max_wait_ms` budget (or `async: true` + gemini_get_result on a local install), or raise `timeout_ms`. Needs a funded account. Local file inputs are confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
- **gemini_music_generate** — Generate music from a text prompt (mood, genre, instruments, structure, or lyrics inline) via a Lyria model: lyria-3-clip-preview (30s instrumental clip, default, cheapest), lyria-3.5 (full-length song with vocals) or lyria-3-pro-preview (longer-form). Output is MP3, written to disk (or returned inline). Single-turn: a track cannot be refined by a follow-up call, so put the whole brief in the prompt. Runs long — give it a `max_wait_ms` budget (or `async: true` + gemini_get_result on a local install), or raise `timeout_ms`. Needs a funded account. Local file inputs are confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
- **gemini_get_result** — Retrieve a generation started with `async: true` or handed off by `max_wait_ms`. Pass the returned `job_id`: while running it reports status "running"; on completion it returns the normal result (image URLs/paths + meta); on failure it raises the recorded error, including the case where the generation was killed before it finished. On the hosted connector job records are stored durably and survive a restart; on a local stdio server they live with the process and expire ~10 min after completion, where the output dir / <image>.json sidecar is the fallback. A killed video/music job started with `background: true` is recovered from its upstream interaction when it finished there.
- **gemini_token_usage** — Token usage for this session so far — what every generation has cost in tokens, added up. Call it before and after a workflow and subtract to get that workflow's cost; call it after a single generation for that call's. Reports tokens AND an estimated USD cost, priced per call against each call's own model and stamped with the date its rates were read (override with GEMINI_RATE_CARD). Note there is no account-balance endpoint to query — Google Cloud is post-paid and its billing data lags by hours — so this is the accurate way to attribute spend to a call.
- **gemini_upload_file** — Upload a file — an image, reference photo, picture, screenshot, video or audio clip — to the Gemini Files API ONCE, and get back a reusable `file_uri` (`files/<id>`) to attach to later image, video or music generations. Keywords: upload, upload file, upload image, upload photo, attach, reference image, reference photo, file_uri, files api, image reference, reuse across calls. Use this instead of pasting base64 into a tool call: the reference is a short string, so no image bytes ever enter the conversation, and it can be reused across many generations until it expires (~48h). Provide exactly one of `url` (the server downloads it), `data_base64`, or `path` (a local file). A local `path` is confirmed first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).
- **gemini_list_files** — List files, images and photos currently uploaded to the Gemini Files API under this API key, with their reusable `file_uri` (`files/<id>`) references, MIME types and expiry times. Retention is ~48h, so an entry that has vanished has expired rather than failed.
- **gemini_delete_file** — Delete an uploaded file, image or photo (by file_uri) from the Gemini Files API before its ~48h expiry. Any tool call still referencing it will then fail with a generic 404, so delete only references you are finished with. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

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

```json
"mcpServers": {
  "gemini-mcp": {
    "command": "npx",
    "args": ["-y","@chrischall/gemini-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-mcp does

gemini-mcp exposes Google Gemini media generation through the Model Context Protocol. Its image tools use the Nano Banana and Nano Banana Pro model families to create images, perform edits, compose multiple references, or produce a master image followed by a consistent set of related images. The server also supports Gemini omni video generation and Lyria music generation.

Image workflows can be single-turn or iterative. `gemini_interact` uses the Gemini Interactions API and returns an interaction identifier that can be supplied to a later call. This supports progressive refinement without treating each edit as an unrelated request.

Results are normally saved to disk, with the resulting path returned to the client. Calls can instead return media inline as base64. Long-running generations can be started asynchronously and retrieved later by job ID.

## How it works

The server communicates with the Gemini v1beta API at `generativelanguage.googleapis.com`. Image generation and editing accept text prompts and, where applicable, image references. Reference images can be supplied as URLs, base64 data, local paths, or uploaded `files/<id>` references. Uploaded Gemini Files API objects can be listed and deleted, and their roughly 48-hour lifetime makes them suitable for temporary reuse.

For iterative calls, pass the prior `interaction_id` as `previous_interaction_id`, or use `continue_last: true`. The server can retry temporary visibility delays for chained interactions and can recover a chain from sidecar metadata saved with an output image. A call using `async: true` returns a `job_id`; use `gemini_get_result` until the job reaches `done`.

Video output is written as MP4. Music output is written as MP3. Video generation supports text-to-video, image-to-video, two-still interpolation, editing, and extension. Resolution options include 360p, 720p, 1080p, and 4K. Music generation uses a Lyria model and is single-turn.

## Setup and configuration

Set `GEMINI_API_KEY` to a Google Gemini API key. Optional variables select the default image model, output and input directories, local-file restrictions, request timeouts, progress heartbeat frequency, and interaction-chain retry duration.

`GEMINI_OUTPUT_DIR` defaults to `~/Downloads/gemini-mcp`. `GEMINI_INPUT_DIR` lets bare input filenames resolve against a chosen directory. `GEMINI_UPLOAD_DIR` and `GEMINI_REFERENCE_DIR` restrict which local files may be sent to Google; reference files in the output directory remain allowed.

The server asks for confirmation before sending local files to Google and before deletions. `MCP_CONFIRM_MODE`, `MCP_CONFIRM_ELICITATION`, `MCP_CONFIRM_TTL_SECONDS`, and `MCP_CONFIRM_SECRET` control confirmation behavior, token lifetime, and token persistence. Pure text prompts, URLs, Files API references, and base64 inputs do not require this confirmation.

## Tools and capabilities

- List available image models and identify the current default.
- Generate, edit, and compose images from prompts and references.
- Create a master image and consistent follow-up images.
- Refine images across multiple Interactions API turns.
- Generate short videos with the Gemini omni model.
- Generate Lyria music clips or full-length music, depending on the selected model.
- Upload, list, and delete reusable Gemini Files API references.
- Poll asynchronous jobs and estimate session token usage and cost.
- In hosted deployments, sign generated media URLs, view generated images inline, and maintain named character and style presets.

## Limitations and notes

The Gemini API key is required, and media generation can exceed an MCP client's tool-call timeout. Progress heartbeats may help hosts that reset their timeout, while asynchronous jobs avoid waiting for the generation inside the original call. An idempotency key can make retries return the recorded result instead of charging for a second generation.

Hosted-only capabilities include signed media access, inline media viewing, upload URLs, persistent character libraries, and persistent style presets. Local file paths are subject to the configured directory restrictions, and uploaded Files API references expire after approximately 48 hours. Token usage reports estimate cost from a dated rate card; `GEMINI_RATE_CARD` can override that rate card.

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