Gemini Omni MCP

MCP server for Google's Gemini Omni Flash (gemini-omni-1.1-flash) video model — text-to-video, image-to-video, reference-guided video, and conversational video editing with native audio, straight from your AI agent.

---

Setup

Get a Gemini API key from Google AI Studio, then add the server to your MCP config.

Claude Desktop / Claude Code / Cursor

Add to your MCP config (mcp.json / .claude.json / claude_desktop_config.json):

{
  "mcpServers": {
    "gemini-omni": {
      "command": "uvx",
      "args": ["gemini-omni-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Droid CLI

droid mcp add gemini-omni "uvx gemini-omni-mcp@latest" --env GEMINI_API_KEY=your-api-key-here

Generated MP4s are saved to ~/gemini_omni_videos by default (set OUTPUT_DIR to change).

---

Features

• Text-to-video: prompt-only MP4 generation with generated audio (music, ambience, SFX)
• Image-to-video: animate a single reference image with motion and camera direction
• Reference-to-video: up to 6 reference images to lock subjects, style, or props
• Conversational editing: iterate on a generated video via previous_interaction_id, or upload your own MP4 and edit it
• Video extension: continue a generated or uploaded video by 3-10s per turn, up to 40s total
• First/last-frame interpolation: transition between two images with <FIRST_FRAME> and <LAST_FRAME>
• Prompt role tags: <FIRST_FRAME>, <LAST_FRAME>, and <IMAGE_REF_N> bind reference images to roles
• Timing cues: [0-3s], [3-6s], [6-10s] direct the action beat by beat
• Resolution control: 360p, 720p (default), 1080p, or 4k (upscaled)
• Batch generation: run multiple prompts in conservative parallel batches (max 4)
• URI or inline delivery: robust Files API polling and download built in

Output is 24fps MP4 (3-10s clips, 360p/720p/1080p/4k) with SynthID watermarking.

---

Showcase

All videos below were generated by this server with the Gemini Omni Flash model, sound on.

Corgi on a hoverboard

A corgi wearing tiny goggles rides a glowing hoverboard through a neon-lit Tokyo street at night, rain reflections on the pavement, camera tracking alongside, single continuous shot, cinematic lighting, upbeat synthwave music.

https://github.com/user-attachments/assets/4b9a8e87-7db0-469d-a261-3c354f7fe9b8

Astronaut latte art

An astronaut in a white spacesuit pours latte art into a floating cup inside a cozy moon-base cafe, Earth visible through a large window, steam swirling in low gravity, slow dolly-in, warm lighting, gentle ambient cafe sounds.

https://github.com/user-attachments/assets/88072ef8-1ce4-4c80-a05a-bfb5531d1271

Origami ocean

An origami paper whale swims gracefully through a stylized paper-craft ocean, paper waves folding and unfolding, paper seagulls gliding above, soft sunlight, camera slowly orbiting, calm orchestral score.

https://github.com/user-attachments/assets/c1e31341-e53c-4a55-af12-d6bb9432dcf5

---

Tools

generate_video

Generates or edits one MP4 and returns JSON with video.path, interaction_id, and metadata.

Argument	Type	Description
prompt	string	Scene, motion, camera, lighting, mood, and audio direction
task	string?	text_to_video, image_to_video, reference_to_video, edit, or extend. Inferred if omitted
aspect_ratio	string?	16:9 (default) or 9:16
resolution	string?	360p, 720p (default), 1080p, or 4k
reference_image_paths	list?	Up to 6 local image paths
input_video_path	string?	Local MP4 (10s or less) to upload and edit or extend
delivery	string?	uri (default, recommended) or inline
previous_interaction_id	string?	Continue editing or extending a generated video
enhance_prompt	bool?	Optional LLM prompt enhancement, default false

batch_generate

Runs multiple prompts in parallel batches, capped at 4.

Argument	Type	Description
prompts	list	One prompt per video
task, aspect_ratio, resolution, reference_image_paths, delivery, enhance_prompt	—	Shared across the batch, same semantics as generate_video
batch_size	int?	Parallelism, capped at MAX_BATCH_SIZE

---

Configuration

Everything is configured through environment variables (or a local .env):

Variable	Default	Description
GEMINI_API_KEY	—	Required. GOOGLE_API_KEY also accepted
OUTPUT_DIR	~/gemini_omni_videos	Where generated MP4s are saved
DEFAULT_ASPECT_RATIO	16:9	16:9 or 9:16
DEFAULT_RESOLUTION	720p	360p, 720p, 1080p, or 4k
DEFAULT_DELIVERY	uri	uri or inline
REQUEST_TIMEOUT	300	Generation timeout in seconds
FILE_POLL_INTERVAL	5.0	Seconds between Files API polls
FILE_POLL_TIMEOUT	600	Max seconds waiting for file activation
MAX_BATCH_SIZE	4	Max parallel generations
ENABLE_PROMPT_ENHANCEMENT	false	LLM-enhance prompts before generation
LOG_LEVEL	INFO	Logging level

---

Prompting tips

• By default Omni generates a few different shots with cuts; ask for a "single continuous shot, no scene cuts" when you want one unbroken scene.
• Always include audio direction, for example "gentle ambient sound, no dialogue".
• For edits, keep the prompt short and add "Keep everything else the same".
• To lengthen a video, say "Extend this video" with previous_interaction_id or an uploaded clip of 10s or less; each turn adds 3-10s, up to 40s total. Leave task unset — the API rejects an explicit task together with previous_interaction_id.
• Use <FIRST_FRAME> and <IMAGE_REF_N> tags to bind reference-image roles.
• Timing cues like [0-3s], [3-6s], and [6-10s], or natural language like "Every 2s cut to a new frame", stage your own scene cuts. When extending, 0s refers to the start of the extension.

Limitations

• MP4 clips of 3-10 seconds at 24fps, SynthID-watermarked; 1080p and 4k are upscaled.
• System instructions, temperature, negative prompts, voice edits, YouTube sources, and multi-video reasoning are unsupported.
• Uploaded-video editing and extension are unavailable in some regions.

---

Development

git clone https://github.com/nikships/gemini-omni-mcp
cd gemini-omni-mcp
uv sync --all-extras
uv run ruff format .
uv run ruff check .
uv run mypy gemini_omni_mcp/
uv run pytest
uv build

Releases are automated: every push to main bumps the version and publishes to PyPI (see PUBLISHING.md).

License

Gemini Omni MCP is licensed under the MIT license. See LICENSE for details.