Gemini Media

gemini-media-mcp

面向 Google 生成式媒体模型的 MCP 服务：图像（Nano Banana 2.1 / Pro）、视频（Veo 3.1 和 Gemini Omni Flash）、语音（Gemini 3.8 TTS）和音乐（Lyria 3.5）。它以单个 Go 二进制文件的形式发布，支持 stdio 和 Streamable HTTP（MCP 2026-07-28），可使用 Gemini API 或 Vertex AI，并附带指导 Agent 完整工作流的 Agent 技能，以及适用于 Claude Code、Codex、Gemini CLI、VS Code/Copilot、Cursor 等工具的插件包。

https://github.com/user-attachments/assets/f46970b3-82a6-4364-a40a-922103dbbc70

一个 Agent 每次使用一个工具来调用服务：生成图像并进行编辑、制作视频片段并将其重塑为黏土动画风格、将 768 px 的肖像分块放大至 8K，以及延长镜头。视频素材、旁白和音乐均由该服务生成。

• 模型保持最新，无需发布新版本。 内置目录记录 ID、别名、生命周期、参数和价格。已退役的模型会重定向到替代模型；目录尚未收录的新模型 ID 也能使用。你可以通过热重载 YAML 文件覆盖或扩展目录。
• 关注成本。 每个结果都会报告预估成本，estimate_cost 可在支出前比较不同选项。支出会记录在账本中，并受会话、每日和每月预算限制；超过阈值的调用需要明确批准。
• 适合 Agent 使用。 每个工具都对应一种工作流，错误会以 [kind] message + Hint 的形式返回。图像结果包含内联预览，输出可通过 URI 串联。视频以异步任务形式运行，并支持长轮询和进度通知。
• 内置技能。 六种Agent 技能涵盖每种媒体类型、多资源制作，以及超越 4K 的放大。放大技能会逐块重新渲染照片，并将这些图块拼接成 8K 图像。
• 稳健可靠。 后端和凭据的检测方式与 Google SDK 一致。Vertex 区域按模型选择，内置重试和超时机制，文件会连同来源信息以原子方式写入，HTTP 模式也提供安全默认设置。

从 v0 升级？工具已发生变化。请参阅迁移表。评审还介绍了此前的问题、问题原因以及 v1 的设计。

快速开始

1. 获取凭据。 二选一：

   • 从 Google AI Studio 获取 API key（GEMINI_API_KEY），或
   • 使用已启用 Vertex AI 的 Google Cloud 项目（GOOGLE_CLOUD_PROJECT，并运行 gcloud auth application-default login）。

2. 安装二进制文件。 在 macOS 或 Linux 上：

   mkdir -p ~/.local/bin   # must be on your PATH
   os=$(uname -s | tr '[:upper:]' '[:lower:]'); arch=$(uname -m | sed 's/x86_64/x64/; s/aarch64/arm64/')
   curl -fsSL "https://github.com/mordor-forge/gemini-media-mcp/releases/latest/download/$os.$arch.gemini-media-mcp.tar.gz" \
     | tar -xz -C ~/.local/bin gemini-media-mcp
   gemini-media-mcp version
   

   在 Windows 上，从最新版本下载 windows 压缩包，并将 gemini-media-mcp.exe 放到 PATH 中。使用 Go 1.26+：go install github.com/mordor-forge/gemini-media-mcp/cmd/gemini-media-mcp@latest。

   Gemini CLI 扩展、Claude Desktop 捆绑包和 Docker 镜像都包含该二进制文件，因此可跳过此步骤。

3. 将服务添加到你的 Agent。 以下所有配置都会从 PATH 中运行 gemini-media-mcp。

   Claude Code（插件：服务加技能），通过共享的 mordor-forge marketplace：

   /plugin marketplace add mordor-forge/claude-plugins
   /plugin install gemini-media@mordor-forge
   

   如果你之前从此仓库添加过 mordor-forge，请先运行 /plugin marketplace remove mordor-forge 切换。无论是否切换，你已安装的插件都能继续使用。 或者只添加服务：claude mcp add gemini-media -e GEMINI_API_KEY=... -- gemini-media-mcp

   Codex（~/.codex/config.toml）：

   [mcp_servers.gemini-media]
   command = "gemini-media-mcp"
   env_vars = ["GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_CLOUD_PROJECT", "GOOGLE_CLOUD_LOCATION"]
   tool_timeout_sec = 300   # 4K images and video polls can exceed the 60 s default
   

   Gemini CLI（仅限付费 API key、Vertex AI 和 Gemini Code Assist，自 2026 年 6 月起）：gemini extensions install https://github.com/mordor-forge/gemini-media-mcp

   Antigravity CLI： 按照安装片段中的说明，将服务添加到 ~/.gemini/config/mcp_config.json。

   Claude Desktop： 从最新版本下载 gemini-media-mcp-<version>.mcpb 并打开。

   VS Code / Copilot： code --add-mcp '{"name":"gemini-media","command":"gemini-media-mcp"}'

   Cursor、Windsurf 和其他 mcpServers 风格的客户端（Zed、OpenCode 和 Goose 使用各自的格式，见下文）：

   { "mcpServers": { "gemini-media": { "command": "gemini-media-mcp", "env": { "GEMINI_API_KEY": "..." } } } }
   

   如果桌面应用提示找不到 gemini-media-mcp，说明它无法访问你的 shell PATH：请使用 command -v gemini-media-mcp 获取完整路径。所有客户端以及 Docker 和技能安装程序的配置都列在 packaging/INSTALL-SNIPPETS.md 中。

4. 如果你的 Agent 不会转发环境变量（插件通常不会），请将密钥保存一次：

   echo "$GEMINI_API_KEY" | gemini-media-mcp configure --api-key-stdin
   gemini-media-mcp doctor   # checks credentials, backend and model availability
   

如需改用 Docker 运行：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 （在 Linux 上，--user 会使生成的文件归你所有；具名 /state 卷会在多次运行之间保留支出统计和视频任务）。

工具

工具	功能
generate_image	文本生成图像，最多支持 14 张参考图、1K–4K、多种宽高比、1–4 个变体，以及可选的 Google Search grounding
edit_image	修改现有图像（添加／移除／重设风格／重新打光／扩展画布），同时保留其他部分
tile_image	放大到任意目标尺寸（1K–16K）的第 1 步：规划覆盖目标图像的最低成本裁剪方案，使其符合编辑模型的宽高比（单块最高约 4K，超过该尺寸则使用网格，也可使用人脸等区域）。免费且在本地运行
stitch_tiles	将编辑后的图块与图像对齐、匹配颜色、融合重叠部分，并保存为一张大型 PNG（默认 8K）。免费且在本地运行
generate_video	根据文本、首帧、首尾帧或参考图像生成带原生音频的片段：Veo（4–8 秒，最多 3 张参考图）或 Gemini Omni Flash（omni：3–10 秒，支持从 360p 草稿到 4K，最多 10 张参考图）。返回 jobId
get_video	等待任务完成（长轮询，默认 45 秒）；完成后下载视频。可安全重复调用
extend_video	延续已完成的片段：Omni 最多延长 10 秒（总计 40 秒），Veo 约延长 7 秒（总计最多 148 秒）
edit_video	根据指令修改已完成的片段或最长 10 秒的视频文件（Gemini Omni）
generate_speech	文本转语音（WAV）：单人语音或双人对话，可逐行控制风格，支持 30 种语音
generate_music	生成 30 秒片段或完整歌曲，支持歌词、结构标签、节奏、纯器乐模式和图像灵感
list_models	当前模型、别名、状态、价格；使用 detail 查看支持的参数，使用 live 检查你的密钥可使用哪些模型
estimate_cost	执行请求前估算价格并比较模型
get_usage	按周期、模型和工具估算支出；剩余预算；运行中的任务
get_config	当前后端及其选择原因、输出目录、默认值、警告

每个结果都包含保存文件的路径、gemini-media://files/<name> URI 和费用。你可以将该 URI 作为其他工具的输入。无法读取服务磁盘的客户端（例如通过 HTTP 连接的客户端）可以使用 resources/read 获取文件，支持的文件最大为 64 MB（更大的放大图像仍保存在服务的磁盘上）。

技能

skills/ 目录包含 Agent Skills，用于指导 Agent 掌握各类媒体的完整工作流：意图、提示词编写、模型选择、成本检查、审核和迭代。它们既支持交互式使用，也支持无人值守运行。

技能	适用场景
gemini-image	图像：生成、编辑、多参考图合成、文本渲染
gemini-video	视频：文本／图像生成视频、帧插值、参考素材、Omni 编辑、延续、异步任务
gemini-speech	配音、旁白、双人对话、语音和风格选择
gemini-music	具有结构、歌词和节奏的片段与完整歌曲
gemini-media-production	多素材项目（分镜脚本 → 关键帧 → 视频 → 配音 → 音乐 → ffmpeg 组装），附带预算计划
gemini-upscale	将照片放大到 1K、2K、4K 或 8K：单块最高 4K，超过该尺寸则拼接 4K 图块网格；可选缺陷修复步骤，例如修正不匹配的眼睛。1K 约需 $0.04，8K 约需 $0.50–1.20。它会生成合理的细节，而非还原细节，因此不适用于取证或档案用途

插件安装（Claude Code、Codex、Gemini CLI、VS Code）包含这些技能。若要在任何兼容 Agent Skills 的 Agent 中安装，请运行 npx skills add mordor-forge/gemini-media-mcp，或将文件夹复制到 .agents/skills/ 或 ~/.claude/skills/。

模型

使用别名或完整模型 ID。运行 gemini-media-mcp models 查看包含价格的内置目录，或调用 list_models；该工具也会应用你的覆盖文件，并在设置 live: true 时检查你的密钥可以使用哪些模型。

媒体	别名（默认项在前）
图像	nb2（Nano Banana 2.1，默认）、pro（Nano Banana Pro：保真度最高）、nb2-lite（输入成本最低）
视频	omni（Gemini Omni Flash，Gemini API 上的默认项：遵循提示词、编辑、延长至 40 s；仅限 Gemini API）、lite（成本最低的 Veo，在 Vertex AI 上为默认项）、fast（Veo 4K、参考图、延长）、standard（Veo 质量最高）
语音	tts（Gemini 3.8 Flash TTS）、tts-lite、tts-2.5、tts-pro
音乐	clip（30 s）、full（Lyria 3.5 歌曲）

Gemini API 上的 Veo。 Google 将于 2026-10-22 停用 Gemini API 上的 Veo 3.1 预览版（以及 gemini-omni-flash-preview 模型）。在此之前，lite、fast 和 standard 仍可使用，但会显示弃用警告；此后，服务端将改用 omni，并会说明原因。Veo 3.1 在 Vertex AI 上仍可用，该平台现称为 Gemini Enterprise Agent Platform（veo-3.1-*-generate-001）：要继续使用它，请让服务端连接到 Google Cloud 项目：设置 GOOGLE_CLOUD_PROJECT 并运行 gcloud auth application-default login；如果也设置了 API 密钥，则设置 GEMINI_MEDIA_BACKEND=vertex（参见配置）。

无需等待版本发布即可更新或添加模型。 创建 YAML 文件，并将 GEMINI_MEDIA_CATALOG 指向该文件。服务端会按 id 将其与内置目录合并，并自动重新加载：

defaults:
  video: fast
models:
  - id: veo-3.1-fast-generate-preview
    pricing: { perSecond: { 720p: 0.10, 1080p: 0.12, 4k: 0.30 } }
  - id: veo-4.0-generate-preview        # a brand-new model
    aliases: [veo4]
    pricing: { perSecond: { 720p: 0.50 } }

完整架构请参见 internal/catalog/models.yaml。

配置

设置的优先级依次为：内置默认值 < 配置文件 < 环境变量 < 标志。Linux 上的配置文件位于 ~/.config/gemini-media-mcp/config.yaml，macOS 上位于 ~/Library/Application Support/gemini-media-mcp/config.yaml，Windows 上位于 %AppData%\gemini-media-mcp\config.yaml，也可以位于 GEMINI_MEDIA_CONFIG 指定的位置。未知键会产生警告而非错误，get_config 会显示每项设置的来源。

环境变量	配置键	默认值	用途
GEMINI_API_KEY / GOOGLE_API_KEY / GEMINI_MEDIA_API_KEY	apiKey	–	Gemini API 密钥（或 Vertex express-mode 密钥）
GEMINI_MEDIA_PROJECT / GOOGLE_CLOUD_PROJECT	project	–	Vertex AI 项目（应用默认凭据）
GEMINI_MEDIA_LOCATION / GOOGLE_CLOUD_LOCATION / GOOGLE_CLOUD_REGION	location	因模型而异	Vertex 区域；未在该区域提供的模型将使用其目录中的区域
GOOGLE_GENAI_USE_VERTEXAI / GOOGLE_GENAI_USE_ENTERPRISE	–	–	true 选择 Vertex AI，false 选择 Gemini API（与 Google SDK 的语义相同）
GEMINI_MEDIA_BACKEND	backend	auto	auto、gemini-api 或 vertex
MEDIA_OUTPUT_DIR / GEMINI_MEDIA_OUTPUT_DIR	outputDir	~/generated_media	媒体的保存位置
GEMINI_MEDIA_STATE_DIR	stateDir	$XDG_STATE_HOME/gemini-media-mcp，否则为 ~/.local/state/gemini-media-mcp（Linux）或配置目录	支出记录和视频任务
GEMINI_MEDIA_BUDGET_SESSION_USD / _DAILY_USD / _MONTHLY_USD	budget.*Usd	无	支出上限（估算值）
GEMINI_MEDIA_CONFIRM_ABOVE_USD	budget.confirmAboveUsd	无	超过此金额的调用需要提供 approvedCostUsd
GEMINI_MEDIA_IMAGE_MODEL / _VIDEO_MODEL / _SPEECH_MODEL / _MUSIC_MODEL / GEMINI_MEDIA_VOICE	defaults.*	目录	默认模型和语音（在此设置的模型会成为两个后端的默认模型；如果当前后端不提供该模型，服务将拒绝启动）
GEMINI_MEDIA_CATALOG	catalogFile	–	目录覆盖文件（热重载）
GEMINI_MEDIA_INPUT_DIRS	inputDirs	–	可读取输入的额外目录（HTTP 模式）
GEMINI_MEDIA_ALLOW_ANY_INPUT_PATH	allowAnyInputPath	stdio 模式下为 true，HTTP 模式下为 false	从磁盘上的任意位置读取输入文件
GEMINI_MEDIA_INLINE_PREVIEWS / GEMINI_MEDIA_PREVIEW_MAX_PIXELS	inlinePreviews / previewMaxPixels	true / 768	为图像结果附加缩小后的预览图，以及预览图的最长边
GEMINI_MEDIA_REQUEST_TIMEOUT_SECONDS	requestTimeoutSeconds	600	每次 Google API 请求的超时时间
GEMINI_MEDIA_MAX_VIDEO_WAIT_SECONDS	maxVideoWaitSeconds	600	视频工具的 waitSeconds 上限
GEMINI_MEDIA_RETRY_ATTEMPTS	retry.attempts	4	遇到速率限制（429）和服务不可用（503）响应时的尝试次数
GEMINI_MEDIA_LOG_LEVEL	logLevel	info	debug、info、warn 或 error（日志输出到 stderr）
GEMINI_MEDIA_TRANSPORT	transport	stdio	stdio 或 http
GEMINI_MEDIA_HTTP_ADDR / GEMINI_MEDIA_HTTP_TOKEN	http.addr / http.authToken	127.0.0.1:8765 / –	HTTP 监听地址和 bearer 令牌
–	http.path	/mcp	HTTP 端点路径
GEMINI_MEDIA_HTTP_ALLOWED_ORIGINS	http.allowedOrigins	–	额外的受信任浏览器来源，以逗号分隔
GEMINI_MEDIA_HTTP_STATEFUL	http.stateful	false	保留每个客户端的会话（仅供需要会话的旧版 2025-11-25 客户端使用）

后端的选择方式：

1. 显式设置的 backend 优先。
2. 否则由 SDK 开关 GOOGLE_GENAI_USE_ENTERPRISE 和 GOOGLE_GENAI_USE_VERTEXAI 决定。
3. 否则，有 API 密钥时选择 Gemini API，即使你的 shell 中为其他工具设置了 GOOGLE_CLOUD_PROJECT 也是如此。
4. 否则，有项目时选择 Vertex AI。

在 Vertex 上，没有项目的 API 密钥会使用 express mode，该模式不支持视频。

支出和预算

Google 不会返回费用，因此服务会根据价格表和 API 报告的 Token 用量计算费用。每次调用运行前都会记录预估费用，运行后会记录核算后的费用。失败和被安全机制拦截的生成按 $0 计算。使用了 Token 但未返回媒体的响应（例如 MAX_TOKENS）会按这些 Token 收费。

• 结果包含 cost {estimatedUsd, usd, basis}。get_usage 和 gemini-media-mcp usage 会汇总支出。账本是状态目录中的纯 JSONL 文件。
• 每次调用前都会检查预算；并发调用之间，以及共享状态目录的多个服务进程之间，都会统一执行预算限制（进行中的调用会在文件锁的保护下预留其预估费用）。
• 设置 GEMINI_MEDIA_CONFIRM_ABOVE_USD=1 后，高费用调用（例如 $3.20 的 Veo 短片）会返回 [confirmation] 错误。Agent 会征求你的确认，然后使用 approvedCostUsd 重试。
• 这些数值都是估算值。如需强制止损，还应在 AI Studio 中设置支出上限，或在 Cloud Billing 中设置预算。

HTTP 模式

GEMINI_API_KEY=... gemini-media-mcp serve --transport http                 # http://127.0.0.1:8765/mcp
GEMINI_MEDIA_HTTP_TOKEN=secret gemini-media-mcp serve --transport http --http-addr 0.0.0.0:8765
claude mcp add --transport http gemini-media http://127.0.0.1:8765/mcp --header "Authorization: Bearer secret"

• HTTP 模式采用无状态 Streamable HTTP，这是 MCP 2026-07-28 的要求；较旧的客户端仍可使用。
• 服务会防范 DNS 重绑定和跨源请求。
• 未提供令牌时，服务拒绝监听非环回地址。
• 服务只会读取输出目录或 GEMINI_MEDIA_INPUT_DIRS 中的输入文件（除非 GEMINI_MEDIA_ALLOW_ANY_INPUT_PATH=true）。
• GET /healthz 会报告状态。

开发

付费实时 E2E 测试会在本地使用你自己的 API 密钥运行。CI 会运行免费检查并编译、检查 E2E 测试，但绝不会执行实时生成，包括合并到 main 之后或手动运行工作流时。

go build ./...
go test -race ./...
golangci-lint run
python3 scripts/validate-skills.py skills
GEMINI_MEDIA_E2E=1 GEMINI_API_KEY=... go test -tags=e2e ./internal/media/ -run E2E -v -timeout 30m   # live, costs cents
# add GEMINI_MEDIA_E2E_VIDEO=1 for the video test (~$0.20), GEMINI_MEDIA_E2E_OMNI=1 for the Omni clip + edit (~$0.30),
# GEMINI_MEDIA_E2E_UPSCALE=1 for a small tiled upscale (~$0.20),
# GEMINI_MEDIA_E2E_OUTPUT_DIR=./e2e-out to keep the files

• AGENTS.md：面向编码 Agent 和贡献者的指南。
• docs/architecture-review.md：架构和设计决策。
• internal/catalog/models.yaml：模型目录。Google 更改模型时，请编辑此文件，而不是修改代码。

许可证

Apache-2.0