mordor-forge/gemini-media-mcp

An MCP server for Google's generative media models: **images** (Nano Banana 2.1 / Pro), **video** (Veo 3.1 and Gemini Omni Flash), **speech** (Gemini 3.8 TTS) and **music** (Lyria 3.5). It ships as a single Go binary, speaks **stdio and Streamable HTTP** (MCP 2026-07-28), works with the **Gemini API or Vertex AI**, and comes with **agent skills** that teach agents the whole workflow, plus plugin packaging for Claude Code, Codex, Gemini CLI, VS Code/Copilot, Cursor and more.
- **Current models, updated without a release.** A built-in catalog records IDs, aliases, lifecycle, parameters and prices. Retired models redirect to their replacement, and new model IDs work before the catalog knows them. You can override or extend the catalog with a hot-reloaded YAML file.
- **Cost-aware.** Every result reports its estimated cost, and estimate_cost compares options before you spend. Spend is recorded in a ledger, capped by session, daily and monthly budgets, and calls above a threshold need explicit approval.
- **Agent-friendly.** Each tool matches a workflow, and errors come back as [kind] message + Hint. Image results include inline previews, and outputs can be chained by URI. Video runs as async jobs with long-polling and progress notifications.
- **Skills included.** Six agent skills cover each medium, multi-asset productions and **upscaling past 4K**. The upscale skill re-renders a photo tile by tile and stitches the tiles into an 8K image.
- **Robust.** Backend and credentials are detected the way the Google SDKs do it. Vertex locations are chosen per model, retries and timeouts are built in, files are written atomically with provenance, and HTTP mode ships with security defaults.
> Upgrading from v0? The tools changed. See the migration table. The review also covers what was broken, why, and the design of v1.
Quick start
1. **Get credentials.** Either:
- an API key from Google AI Studio (GEMINI_API_KEY), or
- a Google Cloud project with Vertex AI enabled (GOOGLE_CLOUD_PROJECT plus gcloud auth application-default login).
2. **Install the binary.** On macOS or Linux:
On Windows, download the windows zip from the latest release and put gemini-media-mcp.exe on your PATH. With Go 1.26+: go install github.com/mordor-forge/gemini-media-mcp/cmd/gemini-media-mcp@latest.
The Gemini CLI extension, the Claude Desktop bundle and the Docker image include the binary, so they skip this step.
3. **Add the server to your agent.** Every config below runs gemini-media-mcp from your PATH.
**Claude Code** (plugin: server plus skills):
or just the server: claude mcp add gemini-media -e GEMINI_API_KEY=... -- gemini-media-mcp
**Codex** (~/.codex/config.toml):
**Gemini CLI** (paid API keys, Vertex AI and Gemini Code Assist only, since June 2026): gemini extensions install https://github.com/mordor-forge/gemini-media-mcp
**Antigravity CLI:** add the server to ~/.gemini/config/mcp_config.json, as shown in the install snippets.
**Claude Desktop:** download gemini-media-mcp- .mcpb from the latest release and open it.
**VS Code / Copilot:** code --add-mcp '{"name":"gemini-media","command":"gemini-media-mcp"}'
**Cursor, Windsurf and other mcpServers-style clients** (Zed, OpenCode and Goose use their own formats, see below):
If a desktop app reports that gemini-media-mcp was not found, it doesn't see your shell's PATH: use the full path from command -v gemini-media-mcp. Every client, plus Docker and the skills installer, is covered in packaging/INSTALL-SNIPPETS.md.
4. **If your agent doesn't forward environment variables** (plugins often don't), store the key once:
To run it in Docker instead: docker run -i --rm --user "$(id -u):$(id -g)" -e GEMINI_API_KEY -v "$PWD/media:/output" -v gemini-media-state:/state ghcr.io/mordor-forge/gemini-media-mcp
(--user makes the generated files yours on Linux; the named /state volume keeps spend accounting and video jobs between runs).
Tools
| Tool | What it does |
|---|---|
| generate_image | Text-to-image with up to 14 reference images, 1K–4K, many aspect ratios, 1–4 variations, optional Google Search grounding |