@chrischall/gemini-mcp 0.5.0 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Google Gemini image generation and editing — generate and edit images via the Gemini API",
-    "version": "0.5.0"
+    "version": "0.6.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Gemini Images",
       "source": "./",
       "description": "Generate and edit images with Google Gemini image models (Nano Banana / Nano Banana Pro) via natural language prompts",
-      "version": "0.5.0",
+      "version": "0.6.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gemini-mcp",
   "displayName": "Gemini Images",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP server for Google Gemini image generation and editing — generate and edit images via the Gemini API",
   "author": {
     "name": "Chris Hall",

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Hall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,9 @@
 # gemini-mcp
 
+[![CI](https://github.com/chrischall/gemini-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/chrischall/gemini-mcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@chrischall/gemini-mcp)](https://www.npmjs.com/package/@chrischall/gemini-mcp)
+[![license](https://img.shields.io/npm/l/@chrischall/gemini-mcp)](LICENSE)
+
 MCP server for Google Gemini image generation and editing. Exposes four tools to Claude over stdio: list available models, generate images from text prompts, edit or compose images with text instructions, and generate a consistent set of images from a master prompt. Images are written to disk by default (path returned) or returned inline as base64. Built on the Gemini v1beta API (`generativelanguage.googleapis.com`) using the Nano Banana / Nano Banana Pro model family.
 
 Developed and maintained by AI (Claude Code).

package/SKILL.md

@@ -83,14 +83,14 @@ Note: Image generation requires a billing-enabled Google Cloud project.
 ### Image Generation
 | Tool | Description |
 |------|-------------|
-| `gemini_generate_image(prompt, count?, images?, images_base64?, video_url?, google_search?, seed?, filename?, model?, aspect_ratio?, image_size?, thinking_level?, output_dir?, inline?)` | Generate image(s) from a text prompt (optionally image-conditioned via `images`/`images_base64`, or video-conditioned via `video_url`) |
+| `gemini_generate_image(prompt, count?, images?, images_base64?, video_url?, video_path?, google_search?, seed?, filename?, model?, aspect_ratio?, image_size?, thinking_level?, output_dir?, inline?)` | Generate image(s) from a text prompt (optionally image-conditioned via `images`/`images_base64`, or video-conditioned via `video_url`/`video_path`) |
 | `gemini_edit_image(prompt, images?, images_base64?, google_search?, seed?, filename?, model?, aspect_ratio?, image_size?, thinking_level?, output_dir?, inline?)` | Edit or compose input image(s) — by **path** (`images`) or **value** (`images_base64`: data URI or raw base64) — with a text instruction. Requires ≥1 input |
 | `gemini_generate_set(master_prompt, scenes? \| count?, reference_mode?, master_images?, master_images_base64?, google_search?, seed?, basename?, model?, thinking_level?, ...)` | Master image (optionally seeded from a reference photo) plus N consistent images referencing it |
 
 ### Multi-turn (Interactions API — Beta)
 | Tool | Description |
 |------|-------------|
-| `gemini_interact(input, previous_interaction_id?, images?, images_base64?, video_url?, google_search?, model?, aspect_ratio?, image_size?, thinking_level?, filename?, output_dir?, inline?)` | Generate/edit via Gemini's **Interactions API**. Returns an `interaction_id`; pass it back as `previous_interaction_id` to **iteratively refine the same image** conversationally — the recommended way to make incremental edits. Output is **JPEG**. (Beta API.) |
+| `gemini_interact(input, previous_interaction_id?, images?, images_base64?, video_url?, video_path?, google_search?, model?, aspect_ratio?, image_size?, thinking_level?, filename?, output_dir?, inline?)` | Generate/edit via Gemini's **Interactions API**. Returns an `interaction_id`; pass it back as `previous_interaction_id` to **iteratively refine the same image** conversationally — the recommended way to make incremental edits. Output is **JPEG**. (Beta API.) |
 
 ## Workflows
 
@@ -179,7 +179,7 @@ extraction:
 - **`thinking_level`** (`minimal`/`high`, Gemini 3 models) controls reasoning depth — `high` can improve complex compositions/edits at higher latency/cost.
 - **Model text.** When the model returns a caption/explanation (mostly Gemini 3 **Pro**), it's surfaced as `text` in the result metadata.
 - **`google_search: true`** grounds the image in live Google Search (current events, weather, real data — great for infographics). The result metadata includes `grounding` with the `queries` run and the `sources` (`{uri, title}`) used. (`gemini_interact` surfaces `grounding.queries` only — the Interactions API returns no clean source list.)
-- **`video_url`** (a public YouTube URL, on `gemini_generate_image` / `gemini_interact`) generates an image from a video reference — **requires a Flash model** (e.g. `model: "gemini-3.1-flash-image"`). Non-YouTube video (Files API upload) is not supported.
+- **`video_url`** (a public YouTube URL, on `gemini_generate_image` / `gemini_interact`) generates an image from a video reference — **requires a Flash model** (e.g. `model: "gemini-3.1-flash-image"`). For a **local video file**, use **`video_path`** instead: the file is uploaded to the Gemini Files API (streamed from disk, 2 GB max), waited to `ACTIVE`, and referenced by its `files/…` uri. The result metadata echoes `video_file` (`{uri, name, expires}`, ~48h retention) — reuse that uri as `video_url` in later calls to skip re-uploading.
 - **`gemini_interact`** is the multi-turn path: it returns an `interaction_id`; thread it back via `previous_interaction_id` for conversational refinement. Output is **JPEG only**. It's a **Beta** API (separate from the stable `generate`/`edit`/`set` tools).
 - `output_dir` per-call overrides `$GEMINI_OUTPUT_DIR` overrides cwd. `inline: true` returns bytes (with a metadata text block) instead of writing.
 - `count` and `scenes` are mutually exclusive in `gemini_generate_set`; `reference_mode: "chain"` references the previous image instead of the master.

package/dist/bundle.js

@@ -32192,6 +32192,19 @@ var init_config = __esm({
 });
 
 // node_modules/@chrischall/mcp-utils/dist/fs/index.js
+import { openAsBlob } from "node:fs";
+async function fileBlob(path, opts = {}) {
+  let blob;
+  try {
+    blob = await openAsBlob(path, opts.type !== void 0 ? { type: opts.type } : void 0);
+  } catch {
+    throw new Error(`Cannot read file for upload: ${path}`);
+  }
+  if (opts.maxBytes !== void 0 && blob.size > opts.maxBytes) {
+    throw new Error(`${opts.label ?? "File"} is ${blob.size} bytes, over the ${opts.maxBytes}-byte limit: ${path}`);
+  }
+  return blob;
+}
 var init_fs = __esm({
   "node_modules/@chrischall/mcp-utils/dist/fs/index.js"() {
   }
@@ -32479,14 +32492,14 @@ var init_clipboard = __esm({
 init_dist();
 
 // src/version.ts
-var VERSION = "0.5.0";
+var VERSION = "0.6.0";
 
 // src/tools/models.ts
 init_dist();
 
 // src/client.ts
 init_dist();
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/models.ts
@@ -32510,11 +32523,17 @@ var SERVICE = "Gemini";
 var INTERACTIONS_SERVICE = "Gemini Interactions";
 var API_REVISION = "2026-05-20";
 var REQUEST_TIMEOUT_MS = 6e4;
+var UPLOAD_BASE_URL = "https://generativelanguage.googleapis.com/upload/v1beta";
+var FILE_MAX_BYTES = 2 * 1024 ** 3;
+var FILE_POLL_INTERVAL_MS = 2e3;
+var FILE_POLL_MAX_ATTEMPTS = 150;
 var GeminiClient = class {
   apiKey;
   configError;
   api;
   interactionsApi;
+  fetchImpl;
+  sleep;
   constructor(opts = {}) {
     const key = readEnvVar("GEMINI_API_KEY");
     if (!key) {
@@ -32526,11 +32545,13 @@ var GeminiClient = class {
       this.apiKey = key;
       this.configError = null;
     }
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     const shared = {
       tokenHeader: "x-goog-api-key",
       getToken: () => this.requireKey(),
       timeout: REQUEST_TIMEOUT_MS,
-      fetchImpl: opts.fetchImpl ?? fetch
+      fetchImpl: this.fetchImpl
     };
     this.api = createApiClient({ baseUrl: BASE_URL, serviceName: SERVICE, ...shared });
     this.interactionsApi = createApiClient({
@@ -32551,6 +32572,93 @@ var GeminiClient = class {
   async call(method, path, body) {
     return this.api.fetchJson(method, path, body !== void 0 ? { body } : {});
   }
+  /**
+   * Upload a local video to the Gemini Files API (resumable protocol) and wait
+   * for it to become usable. Three live-verified steps (docs/GEMINI-API.md
+   * "Files API — local video upload"):
+   *
+   *  1. `POST {UPLOAD_BASE_URL}/files` (command `start`) → the upload session
+   *     URL arrives in the `x-goog-upload-url` RESPONSE HEADER (body is empty).
+   *  2. `POST <session url>` (command `upload, finalize`) with the bytes —
+   *     a file-backed Blob (`fileBlob`/`fs.openAsBlob`), so fetch STREAMS the
+   *     video from disk; it is never buffered in memory. Response: `{file:…}`.
+   *  3. Poll `GET /v1beta/files/<id>` while `state` is `PROCESSING`, until
+   *     `ACTIVE` (the poll response is the File object UNWRAPPED).
+   *
+   * These two upload calls are raw `fetchImpl` (not `createApiClient`): step 1
+   * needs the response *header* and step 2 posts a binary body — neither fits
+   * `fetchJson`. The poll DOES go through the shared client (timeout + retry).
+   * Uploads deliberately have no abort timeout: a multi-hundred-MB video can
+   * legitimately take longer than any fixed budget.
+   *
+   * Returned files live ~48h (`expirationTime`); per-file cap is 2 GB
+   * (enforced locally before any bytes are sent).
+   */
+  async uploadVideo(path, mimeType) {
+    const key = this.requireKey();
+    const blob = await fileBlob(path, { type: mimeType, maxBytes: FILE_MAX_BYTES, label: "Video" });
+    const startPath = "/files";
+    const startRes = await this.fetchImpl(`${UPLOAD_BASE_URL}${startPath}`, {
+      method: "POST",
+      headers: {
+        "x-goog-api-key": key,
+        "X-Goog-Upload-Protocol": "resumable",
+        "X-Goog-Upload-Command": "start",
+        "X-Goog-Upload-Header-Content-Length": String(blob.size),
+        "X-Goog-Upload-Header-Content-Type": mimeType,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ file: { display_name: basename(path) } })
+    });
+    if (!startRes.ok) {
+      throw new McpToolError(
+        formatApiError(startRes.status, "POST", `/upload/v1beta${startPath}`, await startRes.text(), { service: SERVICE })
+      );
+    }
+    const uploadUrl = startRes.headers.get("x-goog-upload-url");
+    if (!uploadUrl) {
+      throw new McpToolError(`${SERVICE} upload start did not return an x-goog-upload-url header`, {
+        hint: "The Files API resumable-upload contract may have changed \u2014 see docs/GEMINI-API.md."
+      });
+    }
+    const upRes = await this.fetchImpl(uploadUrl, {
+      method: "POST",
+      headers: {
+        "X-Goog-Upload-Offset": "0",
+        "X-Goog-Upload-Command": "upload, finalize"
+      },
+      body: blob
+    });
+    if (!upRes.ok) {
+      throw new McpToolError(
+        formatApiError(upRes.status, "POST", "/upload/v1beta/files (finalize)", await upRes.text(), { service: SERVICE })
+      );
+    }
+    let file2 = (await upRes.json()).file ?? {};
+    const name = file2.name ?? "";
+    if (!/^files\/[\w-]+$/.test(name)) {
+      throw new McpToolError(`${SERVICE} upload returned an unexpected file name: ${name || "(none)"}`);
+    }
+    for (let attempt = 0; file2.state === "PROCESSING"; attempt++) {
+      if (attempt >= FILE_POLL_MAX_ATTEMPTS) {
+        throw new McpToolError(`${SERVICE} video file ${name} is still processing after ${FILE_POLL_INTERVAL_MS * FILE_POLL_MAX_ATTEMPTS / 6e4} minutes`, {
+          hint: "Very long videos can take a while to process \u2014 retry later by passing the file uri as video_url."
+        });
+      }
+      await this.sleep(FILE_POLL_INTERVAL_MS);
+      file2 = await this.call("GET", `/${name}`);
+    }
+    if (file2.state !== "ACTIVE") {
+      throw new McpToolError(
+        `${SERVICE} video file processing failed (state ${file2.state ?? "unknown"})${file2.error?.message ? `: ${file2.error.message}` : ""}`,
+        { hint: "Check the video is a supported format/codec and under 2 GB." }
+      );
+    }
+    if (!file2.uri) {
+      throw new McpToolError(`${SERVICE} did not return a uri for uploaded file ${name}`);
+    }
+    return { name, uri: file2.uri, mimeType: file2.mimeType ?? mimeType, expirationTime: file2.expirationTime };
+  }
   async listModels() {
     const data = await this.call("GET", "/models?pageSize=200");
     return filterImageModels(data.models ?? []);
@@ -32562,7 +32670,7 @@ var GeminiClient = class {
       parts.push({ inline_data: { mime_type: img.mimeType, data: img.base64 } });
     }
     if (opts.videoUrl) {
-      parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: "video/mp4" } });
+      parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: opts.videoMimeType ?? "video/mp4" } });
     }
     const generationConfig = { responseModalities: ["TEXT", "IMAGE"] };
     if (opts.aspectRatio || opts.imageSize) {
@@ -32619,7 +32727,7 @@ var GeminiClient = class {
       inputParts.push({ type: "image", mime_type: img.mimeType, data: img.base64 });
     }
     if (opts.videoUrl) {
-      inputParts.push({ type: "video", uri: opts.videoUrl, mime_type: "video/mp4" });
+      inputParts.push({ type: "video", uri: opts.videoUrl, mime_type: opts.videoMimeType ?? "video/mp4" });
     }
     const responseFormat = { type: "image", mime_type: "image/jpeg" };
     if (opts.aspectRatio) responseFormat.aspect_ratio = opts.aspectRatio;
@@ -32726,7 +32834,7 @@ async function writeImage(dir, base, base643, mimeType) {
   await writeFile(path, Buffer.from(base643, "base64"));
   return resolve(path);
 }
-function resolveImagePath(p) {
+function resolveInputPath(p, kind) {
   if (isAbsolute(p) && existsSync(p)) return p;
   const inputDir = readEnvVar("GEMINI_INPUT_DIR");
   if (inputDir) {
@@ -32735,12 +32843,40 @@ function resolveImagePath(p) {
   }
   const cwd = resolve(p);
   if (existsSync(cwd)) return cwd;
-  const hint = "Set GEMINI_INPUT_DIR to a directory containing your images, or pass an absolute path.";
+  const hint = `Set GEMINI_INPUT_DIR to a directory containing your ${kind.toLowerCase()}s, or pass an absolute path.`;
   throw new McpToolError(
-    `Image not found: ${p}` + (inputDir ? ` (also searched GEMINI_INPUT_DIR=${inputDir})` : ""),
+    `${kind} not found: ${p}` + (inputDir ? ` (also searched GEMINI_INPUT_DIR=${inputDir})` : ""),
     { hint }
   );
 }
+function resolveImagePath(p) {
+  return resolveInputPath(p, "Image");
+}
+function resolveVideoPath(p) {
+  return resolveInputPath(p, "Video");
+}
+var VIDEO_MIME_BY_EXT = {
+  mp4: "video/mp4",
+  mpeg: "video/mpeg",
+  mpg: "video/mpg",
+  mov: "video/mov",
+  avi: "video/avi",
+  flv: "video/x-flv",
+  webm: "video/webm",
+  wmv: "video/wmv",
+  "3gp": "video/3gpp",
+  "3gpp": "video/3gpp"
+};
+function videoMimeType(p) {
+  const ext = p.includes(".") ? p.slice(p.lastIndexOf(".") + 1).toLowerCase() : "";
+  const mime = VIDEO_MIME_BY_EXT[ext];
+  if (!mime) {
+    throw new McpToolError(`Unsupported video format: ${ext ? `.${ext}` : p}`, {
+      hint: `Supported extensions: ${Object.keys(VIDEO_MIME_BY_EXT).map((e) => `.${e}`).join(", ")}`
+    });
+  }
+  return mime;
+}
 async function readImageAsInline(path) {
   const resolved = resolveImagePath(path);
   const buf = await readFile2(resolved);
@@ -32798,6 +32934,20 @@ var sharedImageSchema = {
   google_search: external_exports.boolean().optional().describe("Ground the image in live Google Search results (current events, weather, data)"),
   from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)")
 };
+async function resolveVideoInput(args) {
+  if (args.video_url && args.video_path) {
+    throw new McpToolError("Provide `video_url` OR `video_path`, not both.");
+  }
+  if (!args.video_path) return { videoUrl: args.video_url };
+  const path = resolveVideoPath(args.video_path);
+  const uploaded = await client.uploadVideo(path, videoMimeType(args.video_path));
+  const videoFileMeta = { uri: uploaded.uri, name: uploaded.name };
+  if (uploaded.expirationTime) videoFileMeta.expires = uploaded.expirationTime;
+  return { videoUrl: uploaded.uri, videoMimeType: uploaded.mimeType, videoFileMeta };
+}
+var videoPathSchema = external_exports.string().optional().describe(
+  "Path to a local video file \u2014 uploaded to the Gemini Files API (~48h retention, 2 GB max) and used as the video reference. Alternative to video_url."
+);
 function pickSeed(seed) {
   return seed ?? Math.floor(Math.random() * 2147483e3);
 }
@@ -32836,7 +32986,8 @@ function registerGenerateTools(server) {
         filename: external_exports.string().optional().describe("Base filename for the output image (extension stripped; default: slugified prompt)"),
         images: external_exports.array(external_exports.string().min(1)).optional().describe("Paths to reference input images (image-conditioned generation)"),
         images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs"),
-        video_url: external_exports.string().url().optional().describe("Public YouTube URL as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
+        video_url: external_exports.string().url().optional().describe("Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
+        video_path: videoPathSchema,
         ...sharedImageSchema
       }
     },
@@ -32846,6 +32997,7 @@ function registerGenerateTools(server) {
       const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
       const slug = args.filename ? baseName(args.filename) : slugify2(args.prompt);
       const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+      const video = await resolveVideoInput(args);
       const named = [];
       let capturedText;
       let capturedGrounding;
@@ -32859,7 +33011,8 @@ function registerGenerateTools(server) {
           seed: seed + i,
           thinkingLevel: args.thinking_level,
           googleSearch: args.google_search,
-          videoUrl: args.video_url
+          videoUrl: video.videoUrl,
+          videoMimeType: video.videoMimeType
         });
         const { images: [img], text } = result;
         if (text && !capturedText) capturedText = text;
@@ -32869,6 +33022,7 @@ function registerGenerateTools(server) {
       const meta3 = buildMeta(model, seed, args);
       if (capturedText) meta3.text = capturedText;
       if (capturedGrounding) meta3.grounding = capturedGrounding;
+      if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
       return emit(named, args, meta3);
     }
   );
@@ -32996,12 +33150,14 @@ function registerInteractTools(server) {
         output_dir: external_exports.string().optional().describe("Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)"),
         inline: external_exports.boolean().optional().describe("Return base64 images inline instead of writing to disk"),
         google_search: external_exports.boolean().optional().describe("Ground the image in live Google Search results (current events, weather, data)"),
-        video_url: external_exports.string().url().optional().describe("Public YouTube URL as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
+        video_url: external_exports.string().url().optional().describe("Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
+        video_path: videoPathSchema,
         from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)")
       }
     },
     async (args) => {
       const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+      const video = await resolveVideoInput(args);
       const r = await client.interact({
         input: args.input,
         images: inputs.length ? inputs : void 0,
@@ -33011,12 +33167,14 @@ function registerInteractTools(server) {
         thinkingLevel: args.thinking_level,
         previousInteractionId: args.previous_interaction_id,
         googleSearch: args.google_search,
-        videoUrl: args.video_url
+        videoUrl: video.videoUrl,
+        videoMimeType: video.videoMimeType
       });
       const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
       const meta3 = { model, interaction_id: r.id };
       if (r.text) meta3.text = r.text;
       if (r.grounding) meta3.grounding = r.grounding;
+      if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
       const slug = args.filename ? baseName(args.filename) : slugify2(args.input);
       const named = r.images.map((image, i) => ({
         image,

package/dist/client.js

@@ -1,6 +1,6 @@
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadDotenvSafely, readEnvVar, McpToolError, createApiClient } from '@chrischall/mcp-utils';
+import { loadDotenvSafely, readEnvVar, McpToolError, createApiClient, formatApiError, fileBlob } from '@chrischall/mcp-utils';
 import { resolveModel, filterImageModels } from './models.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
@@ -13,11 +13,24 @@ const API_REVISION = '2026-05-20';
 // Per-request abort budget. Image generation routinely runs 30s+ on the Pro
 // model, so this is deliberately 60s (NOT the fleet's usual 15–30s).
 const REQUEST_TIMEOUT_MS = 60_000;
+// Files API (local-video upload — docs/GEMINI-API.md "Files API — local video
+// upload", verified 2026-06-12). The resumable upload endpoint lives under
+// `/upload/v1beta`, NOT the normal `/v1beta` base.
+const UPLOAD_BASE_URL = 'https://generativelanguage.googleapis.com/upload/v1beta';
+// Documented Files API per-file cap (2 GB); enforced locally so a too-big video
+// fails fast instead of uploading gigabytes just to be rejected.
+const FILE_MAX_BYTES = 2 * 1024 ** 3;
+// PROCESSING→ACTIVE poll: every 2s for up to 5 minutes. A 2s clip went ACTIVE
+// in ~1s (verified); longer videos take proportionally longer to process.
+const FILE_POLL_INTERVAL_MS = 2_000;
+const FILE_POLL_MAX_ATTEMPTS = 150;
 export class GeminiClient {
     apiKey;
     configError;
     api;
     interactionsApi;
+    fetchImpl;
+    sleep;
     constructor(opts = {}) {
         const key = readEnvVar('GEMINI_API_KEY');
         if (!key) {
@@ -36,11 +49,13 @@ export class GeminiClient {
         // `getToken` calls requireKey() so key resolution stays at REQUEST time:
         // the server boots without a key and the actionable config error (with its
         // aistudio hint) surfaces on the first tool call, not at startup.
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
         const shared = {
             tokenHeader: 'x-goog-api-key',
             getToken: () => this.requireKey(),
             timeout: REQUEST_TIMEOUT_MS,
-            fetchImpl: opts.fetchImpl ?? fetch,
+            fetchImpl: this.fetchImpl,
         };
         this.api = createApiClient({ baseUrl: BASE_URL, serviceName: SERVICE, ...shared });
         // Separate client for the beta Interactions API: same base URL, but every
@@ -64,6 +79,93 @@ export class GeminiClient {
     async call(method, path, body) {
         return this.api.fetchJson(method, path, body !== undefined ? { body } : {});
     }
+    /**
+     * Upload a local video to the Gemini Files API (resumable protocol) and wait
+     * for it to become usable. Three live-verified steps (docs/GEMINI-API.md
+     * "Files API — local video upload"):
+     *
+     *  1. `POST {UPLOAD_BASE_URL}/files` (command `start`) → the upload session
+     *     URL arrives in the `x-goog-upload-url` RESPONSE HEADER (body is empty).
+     *  2. `POST <session url>` (command `upload, finalize`) with the bytes —
+     *     a file-backed Blob (`fileBlob`/`fs.openAsBlob`), so fetch STREAMS the
+     *     video from disk; it is never buffered in memory. Response: `{file:…}`.
+     *  3. Poll `GET /v1beta/files/<id>` while `state` is `PROCESSING`, until
+     *     `ACTIVE` (the poll response is the File object UNWRAPPED).
+     *
+     * These two upload calls are raw `fetchImpl` (not `createApiClient`): step 1
+     * needs the response *header* and step 2 posts a binary body — neither fits
+     * `fetchJson`. The poll DOES go through the shared client (timeout + retry).
+     * Uploads deliberately have no abort timeout: a multi-hundred-MB video can
+     * legitimately take longer than any fixed budget.
+     *
+     * Returned files live ~48h (`expirationTime`); per-file cap is 2 GB
+     * (enforced locally before any bytes are sent).
+     */
+    async uploadVideo(path, mimeType) {
+        const key = this.requireKey();
+        const blob = await fileBlob(path, { type: mimeType, maxBytes: FILE_MAX_BYTES, label: 'Video' });
+        // 1. start — establish the resumable upload session
+        const startPath = '/files';
+        const startRes = await this.fetchImpl(`${UPLOAD_BASE_URL}${startPath}`, {
+            method: 'POST',
+            headers: {
+                'x-goog-api-key': key,
+                'X-Goog-Upload-Protocol': 'resumable',
+                'X-Goog-Upload-Command': 'start',
+                'X-Goog-Upload-Header-Content-Length': String(blob.size),
+                'X-Goog-Upload-Header-Content-Type': mimeType,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ file: { display_name: basename(path) } }),
+        });
+        if (!startRes.ok) {
+            throw new McpToolError(formatApiError(startRes.status, 'POST', `/upload/v1beta${startPath}`, await startRes.text(), { service: SERVICE }));
+        }
+        const uploadUrl = startRes.headers.get('x-goog-upload-url');
+        if (!uploadUrl) {
+            throw new McpToolError(`${SERVICE} upload start did not return an x-goog-upload-url header`, {
+                hint: 'The Files API resumable-upload contract may have changed — see docs/GEMINI-API.md.',
+            });
+        }
+        // 2. upload + finalize — single shot; the session URL is self-authorizing
+        // (no api-key header needed; verified live).
+        const upRes = await this.fetchImpl(uploadUrl, {
+            method: 'POST',
+            headers: {
+                'X-Goog-Upload-Offset': '0',
+                'X-Goog-Upload-Command': 'upload, finalize',
+            },
+            body: blob,
+        });
+        if (!upRes.ok) {
+            throw new McpToolError(formatApiError(upRes.status, 'POST', '/upload/v1beta/files (finalize)', await upRes.text(), { service: SERVICE }));
+        }
+        let file = (await upRes.json()).file ?? {};
+        // The server echoes the resource name (`files/<id>`); it is interpolated
+        // into the poll path below, so reject anything that could escape the
+        // `/files/` segment (same posture as the model-id guard).
+        const name = file.name ?? '';
+        if (!/^files\/[\w-]+$/.test(name)) {
+            throw new McpToolError(`${SERVICE} upload returned an unexpected file name: ${name || '(none)'}`);
+        }
+        // 3. poll PROCESSING → ACTIVE
+        for (let attempt = 0; file.state === 'PROCESSING'; attempt++) {
+            if (attempt >= FILE_POLL_MAX_ATTEMPTS) {
+                throw new McpToolError(`${SERVICE} video file ${name} is still processing after ${(FILE_POLL_INTERVAL_MS * FILE_POLL_MAX_ATTEMPTS) / 60_000} minutes`, {
+                    hint: 'Very long videos can take a while to process — retry later by passing the file uri as video_url.',
+                });
+            }
+            await this.sleep(FILE_POLL_INTERVAL_MS);
+            file = await this.call('GET', `/${name}`);
+        }
+        if (file.state !== 'ACTIVE') {
+            throw new McpToolError(`${SERVICE} video file processing failed (state ${file.state ?? 'unknown'})${file.error?.message ? `: ${file.error.message}` : ''}`, { hint: 'Check the video is a supported format/codec and under 2 GB.' });
+        }
+        if (!file.uri) {
+            throw new McpToolError(`${SERVICE} did not return a uri for uploaded file ${name}`);
+        }
+        return { name, uri: file.uri, mimeType: file.mimeType ?? mimeType, expirationTime: file.expirationTime };
+    }
     async listModels() {
         const data = await this.call('GET', '/models?pageSize=200');
         return filterImageModels(data.models ?? []);
@@ -75,7 +177,7 @@ export class GeminiClient {
             parts.push({ inline_data: { mime_type: img.mimeType, data: img.base64 } });
         }
         if (opts.videoUrl) {
-            parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: 'video/mp4' } });
+            parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: opts.videoMimeType ?? 'video/mp4' } });
         }
         const generationConfig = { responseModalities: ['TEXT', 'IMAGE'] };
         if (opts.aspectRatio || opts.imageSize) {
@@ -138,7 +240,7 @@ export class GeminiClient {
             inputParts.push({ type: 'image', mime_type: img.mimeType, data: img.base64 });
         }
         if (opts.videoUrl) {
-            inputParts.push({ type: 'video', uri: opts.videoUrl, mime_type: 'video/mp4' });
+            inputParts.push({ type: 'video', uri: opts.videoUrl, mime_type: opts.videoMimeType ?? 'video/mp4' });
         }
         const responseFormat = { type: 'image', mime_type: 'image/jpeg' };
         if (opts.aspectRatio)

package/dist/images.js

@@ -58,13 +58,13 @@ export async function writeImage(dir, base, base64, mimeType) {
     return resolve(path);
 }
 /**
- * Resolve an image path, checking (in order):
+ * Resolve an input file path, checking (in order):
  *  1. Absolute path that exists → returned as-is.
  *  2. `GEMINI_INPUT_DIR` env var is set → look for `join(inputDir, p)`.
  *  3. Relative to cwd → `resolve(p)`.
- * Throws a helpful `McpToolError` if none are found.
+ * Throws a helpful `McpToolError` (labelled `kind`) if none are found.
  */
-export function resolveImagePath(p) {
+function resolveInputPath(p, kind) {
     if (isAbsolute(p) && existsSync(p))
         return p;
     const inputDir = readEnvVar('GEMINI_INPUT_DIR');
@@ -78,8 +78,41 @@ export function resolveImagePath(p) {
     const cwd = resolve(p);
     if (existsSync(cwd))
         return cwd;
-    const hint = 'Set GEMINI_INPUT_DIR to a directory containing your images, or pass an absolute path.';
-    throw new McpToolError(`Image not found: ${p}` + (inputDir ? ` (also searched GEMINI_INPUT_DIR=${inputDir})` : ''), { hint });
+    const hint = `Set GEMINI_INPUT_DIR to a directory containing your ${kind.toLowerCase()}s, or pass an absolute path.`;
+    throw new McpToolError(`${kind} not found: ${p}` + (inputDir ? ` (also searched GEMINI_INPUT_DIR=${inputDir})` : ''), { hint });
+}
+/** Resolve an image path (absolute → GEMINI_INPUT_DIR → cwd). */
+export function resolveImagePath(p) {
+    return resolveInputPath(p, 'Image');
+}
+/** Resolve a local video path (absolute → GEMINI_INPUT_DIR → cwd). */
+export function resolveVideoPath(p) {
+    return resolveInputPath(p, 'Video');
+}
+/** Video MIME types the Gemini Files API accepts, by file extension
+ * (docs/GEMINI-API.md "Files API — local video upload"). */
+const VIDEO_MIME_BY_EXT = {
+    mp4: 'video/mp4',
+    mpeg: 'video/mpeg',
+    mpg: 'video/mpg',
+    mov: 'video/mov',
+    avi: 'video/avi',
+    flv: 'video/x-flv',
+    webm: 'video/webm',
+    wmv: 'video/wmv',
+    '3gp': 'video/3gpp',
+    '3gpp': 'video/3gpp',
+};
+/** MIME type for a video file from its extension; throws for unsupported formats. */
+export function videoMimeType(p) {
+    const ext = p.includes('.') ? p.slice(p.lastIndexOf('.') + 1).toLowerCase() : '';
+    const mime = VIDEO_MIME_BY_EXT[ext];
+    if (!mime) {
+        throw new McpToolError(`Unsupported video format: ${ext ? `.${ext}` : p}`, {
+            hint: `Supported extensions: ${Object.keys(VIDEO_MIME_BY_EXT).map((e) => `.${e}`).join(', ')}`,
+        });
+    }
+    return mime;
 }
 /** Read an image file into `{ base64, mimeType }` for an inline_data part. */
 export async function readImageAsInline(path) {

package/dist/tools/generate.js

@@ -3,7 +3,7 @@ import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { client } from '../client.js';
 import { slugify, baseName, gatherImageInputs } from '../images.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta } from './shared.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, resolveVideoInput, videoPathSchema } from './shared.js';
 export function registerGenerateTools(server) {
     server.registerTool('gemini_generate_image', {
         description: 'Generate image(s) from a text prompt with a Gemini image model (Nano Banana / Nano Banana Pro).',
@@ -14,7 +14,8 @@ export function registerGenerateTools(server) {
             filename: z.string().optional().describe('Base filename for the output image (extension stripped; default: slugified prompt)'),
             images: z.array(z.string().min(1)).optional().describe('Paths to reference input images (image-conditioned generation)'),
             images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs'),
-            video_url: z.string().url().optional().describe('Public YouTube URL as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
+            video_url: z.string().url().optional().describe('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)'),
+            video_path: videoPathSchema,
             ...sharedImageSchema,
         },
     }, async (args) => {
@@ -23,6 +24,9 @@ export function registerGenerateTools(server) {
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
         const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
         const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        // Upload ONCE (before the count loop) — every generate call references
+        // the same files/… uri.
+        const video = await resolveVideoInput(args);
         const named = [];
         let capturedText;
         // For count>1, surface the FIRST call's grounding (each call grounds
@@ -40,7 +44,8 @@ export function registerGenerateTools(server) {
                 seed: seed + i,
                 thinkingLevel: args.thinking_level,
                 googleSearch: args.google_search,
-                videoUrl: args.video_url,
+                videoUrl: video.videoUrl,
+                videoMimeType: video.videoMimeType,
             });
             const { images: [img], text } = result;
             if (text && !capturedText)
@@ -54,6 +59,8 @@ export function registerGenerateTools(server) {
             meta.text = capturedText;
         if (capturedGrounding)
             meta.grounding = capturedGrounding;
+        if (video.videoFileMeta)
+            meta.video_file = video.videoFileMeta;
         return emit(named, args, meta);
     });
     server.registerTool('gemini_edit_image', {

package/dist/tools/interact.js

@@ -3,7 +3,7 @@ import { readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { client } from '../client.js';
 import { slugify, baseName, gatherImageInputs } from '../images.js';
-import { emit, ASPECT_RATIOS, IMAGE_SIZES } from './shared.js';
+import { emit, ASPECT_RATIOS, IMAGE_SIZES, resolveVideoInput, videoPathSchema } from './shared.js';
 export function registerInteractTools(server) {
     server.registerTool('gemini_interact', {
         description: "Multi-turn image generation/editing via Gemini's Interactions API (Beta). " +
@@ -58,7 +58,8 @@ export function registerInteractTools(server) {
                 .string()
                 .url()
                 .optional()
-                .describe('Public YouTube URL as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
+                .describe('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)'),
+            video_path: videoPathSchema,
             from_clipboard: z
                 .boolean()
                 .optional()
@@ -66,6 +67,7 @@ export function registerInteractTools(server) {
         },
     }, async (args) => {
         const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        const video = await resolveVideoInput(args);
         const r = await client.interact({
             input: args.input,
             images: inputs.length ? inputs : undefined,
@@ -75,7 +77,8 @@ export function registerInteractTools(server) {
             thinkingLevel: args.thinking_level,
             previousInteractionId: args.previous_interaction_id,
             googleSearch: args.google_search,
-            videoUrl: args.video_url,
+            videoUrl: video.videoUrl,
+            videoMimeType: video.videoMimeType,
         });
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
         const meta = { model, interaction_id: r.id };
@@ -83,6 +86,8 @@ export function registerInteractTools(server) {
             meta.text = r.text;
         if (r.grounding)
             meta.grounding = r.grounding;
+        if (video.videoFileMeta)
+            meta.video_file = video.videoFileMeta;
         const slug = args.filename ? baseName(args.filename) : slugify(args.input);
         const named = r.images.map((image, i) => ({
             image,

package/dist/tools/shared.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
-import { textResult } from '@chrischall/mcp-utils';
-import { writeImage, resolveOutputDir } from '../images.js';
+import { textResult, McpToolError } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+import { writeImage, resolveOutputDir, resolveVideoPath, videoMimeType } from '../images.js';
 /** Supported output aspect ratios (Gemini image API). */
 export const ASPECT_RATIOS = ['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'];
 /** Supported output resolutions. `512` is Flash-only (0.5K); `1K`/`2K`/`4K` work on all image models. */
@@ -28,6 +29,32 @@ export const sharedImageSchema = {
     google_search: z.boolean().optional().describe('Ground the image in live Google Search results (current events, weather, data)'),
     from_clipboard: z.boolean().optional().describe('Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)'),
 };
+/**
+ * Turn the `video_url` / `video_path` tool args into the client's video opts.
+ * A `video_path` is resolved locally (absolute → $GEMINI_INPUT_DIR → cwd),
+ * uploaded to the Gemini Files API (streamed, never buffered), and waited to
+ * `ACTIVE`; the returned `files/…` uri is what the generate call references.
+ * The uploaded file (uri + expiry) is echoed via `videoFileMeta` so a caller
+ * can pass the uri straight back as `video_url` instead of re-uploading.
+ */
+export async function resolveVideoInput(args) {
+    if (args.video_url && args.video_path) {
+        throw new McpToolError('Provide `video_url` OR `video_path`, not both.');
+    }
+    if (!args.video_path)
+        return { videoUrl: args.video_url };
+    const path = resolveVideoPath(args.video_path);
+    const uploaded = await client.uploadVideo(path, videoMimeType(args.video_path));
+    const videoFileMeta = { uri: uploaded.uri, name: uploaded.name };
+    if (uploaded.expirationTime)
+        videoFileMeta.expires = uploaded.expirationTime;
+    return { videoUrl: uploaded.uri, videoMimeType: uploaded.mimeType, videoFileMeta };
+}
+/** Shared zod field for the `video_path` tool param. */
+export const videoPathSchema = z
+    .string()
+    .optional()
+    .describe('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.');
 /**
  * Return the provided seed, or pick a random one. Capped well below INT32_MAX
  * so derived per-image seeds (`seed + i`) can't overflow a 32-bit int.

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Single source of the server version. release-please bumps the literal below. */
-export const VERSION = '0.5.0'; // x-release-please-version
+export const VERSION = '0.6.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "mcpName": "io.github.chrischall/gemini-mcp",
   "description": "Gemini image-generation MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/gemini-mcp",
     "source": "github"
   },
-  "version": "0.5.0",
+  "version": "0.6.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "0.5.0",
+      "version": "0.6.0",
       "transport": {
         "type": "stdio"
       },