1.13.0npm · @chrischall/gemini-mcp · current release
Observed 2026-09-05T00:26:27.413Z using mcpSecurity-inventory. Status: succeeded. Negotiated protocol: 2025-06-18.
{
"tools": {
"listChanged": true
}
}| Tool | Category | Annotations | Risk |
|---|---|---|---|
gemini_delete_fileDelete 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.Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"file_uri": {
"type": "string",
"minLength": 1,
"description": "The `files/<id>` reference (or full uri) to delete"
},
"confirm": {
"description": "Must be true to proceed. Without this, the tool returns a preview.",
"type": "boolean"
}
},
"required": [
"file_uri"
]
}Annotations{
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": true
} | — | Writes · Destructive | — |
gemini_get_resultRetrieve 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.Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "The job_id returned by a generation tool called with async: true"
},
"output_dir": {
"description": "Where to write media recovered from a killed job (default: $GEMINI_OUTPUT_DIR or cwd)",
"type": "string"
}
},
"required": [
"job_id"
]
}Annotations{
"readOnlyHint": false,
"openWorldHint": true
} | — | Writes · — | — |
gemini_healthcheckResolves 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'. Call this when a real tool fails and you want to know which hop broke. Read-only; never returns the credential itself.Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {}
}Annotations{
"title": "Verify credentials and upstream reachability",
"readOnlyHint": true,
"idempotentHint": true,
"openWorldHint": true
} | — | Read only · — | — |
gemini_image_editEdit 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.Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"prompt": {
"type": "string",
"minLength": 1,
"description": "Instruction describing the edit or composition"
},
"images": {
"description": "Paths to input image file(s) (1 = edit, 2+ = compose)",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"images_url": {
"description": "Input images as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*).",
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
},
"images_file_uris": {
"description": "Input images by Gemini Files API reference (\"files/<id>\", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"images_r2_keys": {
"description": "Input images by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket directly — no bytes in the conversation, no signed URL, no ~48h Files API expiry. Hosted connector only.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"images_base64": {
"description": "Input images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"characters": {
"description": "Names of saved characters (see gemini_list_characters / gemini_save_character): each one's reference image and description are attached to the request automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only.",
"maxItems": 8,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"style": {
"description": "Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment — and reference image, if it has one — is applied to the request automatically. Hosted connector only.",
"type": "string",
"minLength": 1
},
"filename": {
"description": "Base filename for the output image (extension stripped; default: slugified prompt)",
"type": "string"
},
"confirm": {
"description": "Must be true to proceed. Without this, the tool returns a preview.",
"type": "boolean"
},
"model": {
"description": "Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse — balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding).",
"type": "string",
"pattern": "^[\\w.-]+$"
},
"aspect_ratio": {
"description": "Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.",
"type": "string",
"enum": [
"1:1",
"2:3",
"3:2",
"3:4",
"4:3",
"4:5",
"5:4",
"9:16",
"16:9",
"21:9",
"1:4",
"4:1",
"1:8",
"8:1"
]
},
"orientation": {
"description": "Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given.",
"type": "string",
"enum": [
"landscape",
"portrait",
"square"
]
},
"image_size": {
"description": "Output resolution (512 = 0.5K, Flash-only)",
"type": "string",
"enum": [
"512",
"1K",
"2K",
"4K"
]
},
"output_dir": {
"description": "Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)",
"type": "string"
},
"inline": {
"description": "Return base64 images inline instead of writing to disk",
"type": "boolean"
},
"seed": {
"description": "Seed for reproducible generation; random if omitted",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"thinking_level": {
"description": "Reasoning depth (Gemini 3 models); higher can help complex/structural edits",
"type": "string",
"enum": [
"minimal",
"high"
]
},
"google_search": {
"description": "Ground the image in live Google Search results (current events, weather, data)",
"type": "boolean"
},
"from_clipboard": {
"description": "Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)",
"type": "boolean"
},
"timeout_ms": {
"description": "Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"idempotency_key": {
"description": "Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge.",
"type": "string",
"minLength": 1
},
"async": {
"description": "Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off.",
"type": "boolean"
},
"max_wait_ms": {
"description": "Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 600000
}
},
"required": [
"prompt"
]
}Annotations{
"readOnlyHint": false,
"openWorldHint": true
} | — | Writes · — | — |
gemini_image_generateGenerate 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.Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"prompt": {
"type": "string",
"minLength": 1,
"description": "Text prompt describing the image"
},
"count": {
"description": "Number of independent images (default 1)",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 8
},
"filename": {
"description": "Base filename for the output image (extension stripped; default: slugified prompt)",
"type": "string"
},
"images": {
"description": "Paths to reference input images (image-conditioned generation)",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"images_url": {
"description": "Reference images as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*).",
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
},
"images_file_uris": {
"description": "Reference images by Gemini Files API reference (\"files/<id>\", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"images_r2_keys": {
"description": "Reference images by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket directly — no bytes in the conversation, no signed URL, no ~48h Files API expiry. Hosted connector only.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"images_base64": {
"description": "Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"characters": {
"description": "Names of saved characters (see gemini_list_characters / gemini_save_character): each one's reference image and description are attached to the request automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only.",
"maxItems": 8,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"style": {
"description": "Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment — and reference image, if it has one — is applied to the request automatically. Hosted connector only.",
"type": "string",
"minLength": 1
},
"video_url": {
"description": "Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)",
"type": "string",
"format": "uri"
},
"video_path": {
"description": "Path to a local video file — uploaded to the Gemini Files API (~48h retention, 2 GB max) and used as the video reference. Alternative to video_url.",
"type": "string"
},
"confirm": {
"description": "Must be true to proceed. Without this, the tool returns a preview.",
"type": "boolean"
},
"model": {
"description": "Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse — balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding).",
"type": "string",
"pattern": "^[\\w.-]+$"
},
"aspect_ratio": {
"description": "Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.",
"type": "string",
"enum": [
"1:1",
"2:3",
"3:2",
"3:4",
"4:3",
"4:5",
"5:4",
"9:16",
"16:9",
"21:9",
"1:4",
"4:1",
"1:8",
"8:1"
]
},
"orientation": {
"description": "Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given.",
"type": "string",
"enum": [
"landscape",
"portrait",
"square"
]
},
"image_size": {
"description": "Output resolution (512 = 0.5K, Flash-only)",
"type": "string",
"enum": [
"512",
"1K",
"2K",
"4K"
]
},
"output_dir": {
"description": "Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)",
"type": "string"
},
"inline": {
"description": "Return base64 images inline instead of writing to disk",
"type": "boolean"
},
"seed": {
"description": "Seed for reproducible generation; random if omitted",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"thinking_level": {
"description": "Reasoning depth (Gemini 3 models); higher can help complex/structural edits",
"type": "string",
"enum": [
"minimal",
"high"
]
},
"google_search": {
"description": "Ground the image in live Google Search results (current events, weather, data)",
"type": "boolean"
},
"from_clipboard": {
"description": "Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)",
"type": "boolean"
},
"timeout_ms": {
"description": "Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"idempotency_key": {
"description": "Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge.",
"type": "string",
"minLength": 1
},
"async": {
"description": "Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off.",
"type": "boolean"
},
"max_wait_ms": {
"description": "Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 600000
}
},
"required": [
"prompt"
]
}Annotations{
"readOnlyHint": false,
"openWorldHint": true
} | — | Writes · — | — |
gemini_image_setGenerate 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.Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"master_prompt": {
"type": "string",
"minLength": 1,
"description": "Prompt for the master/reference image"
},
"scenes": {
"description": "Per-image prompts (1-8); each references the master",
"minItems": 1,
"maxItems": 8,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"count": {
"description": "Number of variations of master_prompt (when scenes omitted)",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 8
},
"reference_mode": {
"description": "master: every image references the master (default). chain: each references the previous.",
"type": "string",
"enum": [
"master",
"chain"
]
},
"basename": {
"description": "Base filename prefix for output images (default: slugified master_prompt)",
"type": "string"
},
"master_images": {
"description": "Reference image paths passed to the master generation call",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"master_images_url": {
"description": "Reference images passed to the master AND to every scene call (fetched once) as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*).",
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
},
"master_images_file_uris": {
"description": "Reference images passed to the master AND to every scene call by Gemini Files API reference (\"files/<id>\", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"master_images_r2_keys": {
"description": "Reference images passed to the master AND to every scene call by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket directly — no bytes in the conversation, no signed URL, no ~48h Files API expiry. Hosted connector only.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"characters": {
"description": "Names of saved characters (see gemini_list_characters / gemini_save_character): each one's reference image and description are attached to the request automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only.",
"maxItems": 8,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"style": {
"description": "Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment — and reference image, if it has one — is applied to the request automatically. Hosted connector only.",
"type": "string",
"minLength": 1
},
"master_images_base64": {
"description": "Reference images as base64 strings or data URIs for master generation. Last resort: prefer master_images_url or master_images_file_uris, which keep image bytes out of the conversation",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"confirm": {
"description": "Must be true to proceed. Without this, the tool returns a preview.",
"type": "boolean"
},
"model": {
"description": "Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse — balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding).",
"type": "string",
"pattern": "^[\\w.-]+$"
},
"aspect_ratio": {
"description": "Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.",
"type": "string",
"enum": [
"1:1",
"2:3",
"3:2",
"3:4",
"4:3",
"4:5",
"5:4",
"9:16",
"16:9",
"21:9",
"1:4",
"4:1",
"1:8",
"8:1"
]
},
"orientation": {
"description": "Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given.",
"type": "string",
"enum": [
"landscape",
"portrait",
"square"
]
},
"image_size": {
"description": "Output resolution (512 = 0.5K, Flash-only)",
"type": "string",
"enum": [
"512",
"1K",
"2K",
"4K"
]
},
"output_dir": {
"description": "Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)",
"type": "string"
},
"inline": {
"description": "Return base64 images inline instead of writing to disk",
"type": "boolean"
},
"seed": {
"description": "Seed for reproducible generation; random if omitted",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"thinking_level": {
"description": "Reasoning depth (Gemini 3 models); higher can help complex/structural edits",
"type": "string",
"enum": [
"minimal",
"high"
]
},
"google_search": {
"description": "Ground the image in live Google Search results (current events, weather, data)",
"type": "boolean"
},
"from_clipboard": {
"description": "Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)",
"type": "boolean"
},
"timeout_ms": {
"description": "Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"idempotency_key": {
"description": "Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge.",
"type": "string",
"minLength": 1
},
"async": {
"description": "Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off.",
"type": "boolean"
},
"max_wait_ms": {
"description": "Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 600000
}
},
"required": [
"master_prompt"
]
}Annotations{
"readOnlyHint": false,
"openWorldHint": true
} | — | Writes · — | — |
gemini_interactPreferred tool for iterative or multi-step refinement of a single image — multi-turn generation/editing via Gemini's Interactions API. To refine, capture the returned interaction `id` and pass it as `previous_interaction_id` on the next call — do NOT start a new interaction or re-upload 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 on the client side, the generation usually still completes: the image plus a `<image>.json` sidecar recording its interaction id land in the output dir, and `continue_last: true` still resumes that interaction — check the output dir before re-issuing (a re-issue is a second billable generation). If a chained call 404s, this tool re-anchors itself on the prior output image and re-issues un-chained: success is reported as `chain_recovered` (the chain was the problem, and you get your image anyway); a second 404 is reported as the interaction id NOT being the cause (check the model id / files uri instead). Output is JPEG.Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"input": {
"type": "string",
"minLength": 1,
"description": "Text prompt or editing instruction"
},
"previous_interaction_id": {
"description": "ID from a prior gemini_interact call — continues that multi-turn conversation",
"type": "string"
},
"continue_last": {
"description": "Continue from the most recent interaction this server created (convenience for previous_interaction_id; an explicit id wins). Survives a server restart by falling back to the newest <image>.json sidecar in the output dir.",
"type": "boolean"
},
"images": {
"description": "Paths to reference input images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"images_url": {
"description": "Reference images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. Given as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*).",
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
},
"images_file_uris": {
"description": "Reference images. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit. Given by Gemini Files API reference (\"files/<id>\", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"images_base64": {
"description": "Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation. NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output — the interaction already contains it, and re-sending it anchors the model against your edit.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"model": {
"description": "Model id override (default: server default; see gemini_list_models). gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse — balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding).",
"type": "string"
},
"aspect_ratio": {
"description": "Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.",
"type": "string",
"enum": [
"1:1",
"2:3",
"3:2",
"3:4",
"4:3",
"4:5",
"5:4",
"9:16",
"16:9",
"21:9",
"1:4",
"4:1",
"1:8",
"8:1"
]
},
"orientation": {
"description": "Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given.",
"type": "string",
"enum": [
"landscape",
"portrait",
"square"
]
},
"image_size": {
"description": "Output resolution (512 = 0.5K, Flash-only)",
"type": "string",
"enum": [
"512",
"1K",
"2K",
"4K"
]
},
"thinking_level": {
"description": "Reasoning depth; higher can help complex/structural edits",
"type": "string",
"enum": [
"minimal",
"high"
]
},
"filename": {
"description": "Base filename for the output image (extension stripped; default: slugified input)",
"type": "string"
},
"output_dir": {
"description": "Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)",
"type": "string"
},
"inline": {
"description": "Return base64 images inline instead of writing to disk",
"type": "boolean"
},
"google_search": {
"description": "Ground the image in live Google Search results (current events, weather, data)",
"type": "boolean"
},
"search_types": {
"description": "Grounding search types (implies google_search). image_search (gemini-3.1-flash-image only) uses Google Image Search results as visual references; per Google ToS the returned grounding.search_suggestions HTML must then be displayed to the user. Cannot depict real people from web images.",
"type": "array",
"items": {
"type": "string",
"enum": [
"web_search",
"image_search"
]
}
},
"video_url": {
"description": "Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)",
"type": "string",
"format": "uri"
},
"video_path": {
"description": "Path to a local video file — uploaded to the Gemini Files API (~48h retention, 2 GB max) and used as the video reference. Alternative to video_url.",
"type": "string"
},
"timeout_ms": {
"description": "Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"idempotency_key": {
"description": "Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge.",
"type": "string",
"minLength": 1
},
"async": {
"description": "Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off.",
"type": "boolean"
},
"max_wait_ms": {
"description": "Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 600000
},
"from_clipboard": {
"description": "Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)",
"type": "boolean"
},
"confirm": {
"description": "Must be true to proceed. Without this, the tool returns a preview.",
"type": "boolean"
}
},
"required": [
"input"
]
}Annotations{
"readOnlyHint": false,
"openWorldHint": true
} | — | Writes · — | — |
gemini_list_filesList 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.Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"page_size": {
"description": "Maximum files to return (1-100, default 100)",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
}
}Annotations{
"readOnlyHint": true,
"openWorldHint": true
} | — | Read only · — | — |
gemini_list_modelsList the Gemini image-generation models available to your API key (Nano Banana / Nano Banana Pro family), and the current default model.Input schema{
"type": "object",
"properties": {}
}Annotations{
"readOnlyHint": true
} | — | Read only · — | — |
gemini_music_generateGenerate music from a text prompt (mood, genre, instruments, structure, or lyrics inline) via a Lyria model (preview): lyria-3-clip-preview (~30s clips, default) or lyria-3-pro-preview (longer, WAV-capable). Written to disk as MP3/WAV (or returned inline). Runs long — use `async: true` + gemini_get_result, or raise `timeout_ms`. Preview model: needs a funded account.Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"prompt": {
"type": "string",
"minLength": 1,
"description": "Description of the music: mood, genre, instruments, tempo, structure, or lyrics"
},
"model": {
"description": "Lyria model (default: lyria-3-clip-preview). Pro is longer-form and supports WAV.",
"type": "string",
"enum": [
"lyria-3-clip-preview",
"lyria-3-pro-preview"
]
},
"audio_format": {
"description": "Output format (default mp3). wav is lyria-3-pro-preview-only.",
"type": "string",
"enum": [
"mp3",
"wav"
]
},
"images": {
"description": "Optional reference image path(s) to condition the music",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"images_url": {
"description": "Reference images as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*).",
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
},
"images_file_uris": {
"description": "Reference images by Gemini Files API reference (\"files/<id>\", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"images_base64": {
"description": "Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"from_clipboard": {
"description": "Use the image currently on the macOS clipboard as a reference",
"type": "boolean"
},
"filename": {
"description": "Base filename for the output audio (extension stripped; default: slugified prompt)",
"type": "string"
},
"output_dir": {
"description": "Directory to write audio to (default: $GEMINI_OUTPUT_DIR or cwd)",
"type": "string"
},
"inline": {
"description": "Return base64 audio inline instead of writing to disk",
"type": "boolean"
},
"previous_interaction_id": {
"description": "Interaction id to continue from",
"type": "string"
},
"continue_last": {
"description": "Continue from the most recent music interaction this server created (explicit previous_interaction_id wins)",
"type": "boolean"
},
"background": {
"description": "Run the generation on Google's side and poll it, so a killed job can be recovered by gemini_get_result. Off by default — see gemini_video_generate",
"type": "boolean"
},
"timeout_ms": {
"description": "Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"idempotency_key": {
"description": "Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge.",
"type": "string",
"minLength": 1
},
"async": {
"description": "Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off.",
"type": "boolean"
},
"max_wait_ms": {
"description": "Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 600000
},
"confirm": {
"description": "Must be true to proceed. Without this, the tool returns a preview.",
"type": "boolean"
}
},
"required": [
"prompt"
]
}Annotations{
"readOnlyHint": false,
"openWorldHint": true
} | — | Writes · — | — |
gemini_token_usageToken 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.Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"reset": {
"description": "Zero the running total after reporting it, so the next call measures from here. Use it to bracket a workflow without arithmetic.",
"type": "boolean"
}
}
}Annotations{
"readOnlyHint": true
} | — | Read only · — | — |
gemini_upload_fileUpload 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).Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"url": {
"description": "Public https URL the SERVER downloads and uploads (image/video/audio, up to 100MB). No bytes pass through the conversation.",
"type": "string",
"format": "uri"
},
"data_base64": {
"description": "Raw base64 or a data: URI. Last resort — this is the one form that costs model context (~14k tokens for a modest JPEG).",
"type": "string",
"minLength": 1
},
"r2_key": {
"description": "Unavailable on this server (media is written to local disk) — pass the file path via `path` instead.",
"type": "string",
"minLength": 1
},
"path": {
"description": "Path to a local file (absolute, or resolved against $GEMINI_INPUT_DIR). Confirm-gated like every other local-file input.",
"type": "string",
"minLength": 1
},
"mime_type": {
"description": "Override the detected MIME type (sniffed from the bytes / taken from the server response otherwise)",
"type": "string",
"pattern": "^[\\w.+-]+\\/[\\w.+-]+$"
},
"display_name": {
"description": "Human-readable name recorded against the upload",
"type": "string",
"minLength": 1
},
"confirm": {
"description": "Must be true to proceed. Without this, the tool returns a preview.",
"type": "boolean"
}
}
}Annotations{
"readOnlyHint": false,
"openWorldHint": true
} | — | Writes · — | — |
gemini_video_generateGenerate a short video via the Gemini omni model (preview): text→video, image→video / reference→video (supply reference image[s]), or edit a prior video (task: "edit" + previous_interaction_id / continue_last). Output is written to disk as MP4 (video has no inline MCP block). Video runs long — use `async: true` to get a job_id immediately and poll gemini_get_result, or raise `timeout_ms`. Preview model: needs a funded account.Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"prompt": {
"type": "string",
"minLength": 1,
"description": "Description of the video to generate (or the edit instruction when task=edit)"
},
"aspect_ratio": {
"description": "Exact output aspect ratio (omni: 16:9 or 9:16). `orientation` is the plain-language shorthand; this wins if both are given.",
"type": "string",
"enum": [
"16:9",
"9:16"
]
},
"orientation": {
"description": "Shape of the output, in plain terms: \"landscape\" (wide, 16:9), \"portrait\" (tall, 9:16) or \"square\" (1:1). Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — 35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, which overrides this when both are given.",
"type": "string",
"enum": [
"landscape",
"portrait",
"square"
]
},
"task": {
"description": "text_to_video (default), image_to_video / reference_to_video (need image input), or edit (needs previous_interaction_id)",
"type": "string",
"enum": [
"text_to_video",
"image_to_video",
"reference_to_video",
"edit"
]
},
"images": {
"description": "Reference image path(s) for image_to_video / reference_to_video",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"images_url": {
"description": "Reference stills as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max 15MB each; must be a directly-linked image (Content-Type image/*).",
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
},
"images_file_uris": {
"description": "Reference stills by Gemini Files API reference (\"files/<id>\", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"images_base64": {
"description": "Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"from_clipboard": {
"description": "Use the image currently on the macOS clipboard as a reference",
"type": "boolean"
},
"filename": {
"description": "Base filename for the output video (extension stripped; default: slugified prompt)",
"type": "string"
},
"output_dir": {
"description": "Directory to write the video to (default: $GEMINI_OUTPUT_DIR or cwd)",
"type": "string"
},
"model": {
"description": "Model id override (default: gemini-omni-flash-preview)",
"type": "string",
"pattern": "^[\\w.-]+$"
},
"delivery": {
"description": "How the clip comes back: \"uri\" (default — a Files API link the server downloads, no size ceiling) or \"inline\" (base64, capped ~4MB)",
"type": "string",
"enum": [
"inline",
"uri"
]
},
"background": {
"description": "Run the generation on Google's side and poll it, so a killed job can be recovered by gemini_get_result. Trade-off: retrieving a backgrounded interaction is unreliable today (some become permanently unreadable), so the default is off",
"type": "boolean"
},
"previous_interaction_id": {
"description": "Interaction id to edit/continue (with task: \"edit\")",
"type": "string"
},
"continue_last": {
"description": "Continue from the most recent video interaction this server created (explicit previous_interaction_id wins)",
"type": "boolean"
},
"timeout_ms": {
"description": "Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"idempotency_key": {
"description": "Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge.",
"type": "string",
"minLength": 1
},
"async": {
"description": "Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off.",
"type": "boolean"
},
"max_wait_ms": {
"description": "Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: \"running\" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 600000
},
"confirm": {
"description": "Must be true to proceed. Without this, the tool returns a preview.",
"type": "boolean"
}
},
"required": [
"prompt"
]
}Annotations{
"readOnlyHint": false,
"openWorldHint": true
} | — | Writes · — | — |