gemini-media-mcp
gemini-media-mcp
用于通过 Google Gemini API 和 Vertex AI 进行 AI 媒体生成的统一 Go MCP 服务器。
功能特性
图像生成 -- 支持可配置宽高比和分辨率(1K/2K/4K)的文生图功能
图像编辑 -- 使用自然语言提示词修改现有图像
多参考图合成 -- 结合最多 3 张参考图,并提供风格/内容引导
视频生成 -- 通过 Veo 3.1 Lite、Fast 和 Standard 层级进行文生视频
图生视频 -- 将静态图像动画化为视频片段
视频扩展 -- 串联片段以制作更长的内容(Fast 和 Standard 层级)
文本转语音 (TTS) -- 生成具有可配置语音和语言的口语音频
音乐生成 -- 通过 Lyria 3 生成 AI 音乐(30 秒片段或带有人声、结构控制的完整歌曲)
单个二进制文件 -- 无运行时依赖,通过 stdio 传输运行
提供商抽象 -- 针对图像、视频、音频和模型操作的后端无关接口
双后端 -- 同时支持 Gemini API(API 密钥)和 Vertex AI(项目凭据)
Related MCP server: Gemini Media MCP
快速开始
# Install
go install github.com/mordor-forge/gemini-media-mcp/cmd/gemini-media-mcp@latest
# Configure (Gemini API; either variable name works)
export GEMINI_API_KEY="your-api-key"
# export GOOGLE_API_KEY="your-api-key"
# Or configure (Vertex AI)
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
# Run directly (stdio transport)
gemini-media-mcp然后将其添加到您的 MCP 客户端中 -- 请参阅下方的 MCP 客户端配置。
配置
变量 | 必需 | 默认值 | 描述 |
| 是* | -- | Gemini API 密钥。也接受 |
| 是* | -- | 用于 Vertex AI 后端的 GCP 项目 ID |
| 否 |
| Vertex AI 的 GCP 区域 |
| 否 |
| 保存媒体文件的目录 |
*必须设置 GOOGLE_API_KEY 或 GOOGLE_CLOUD_PROJECT 中的一个。如果两者都设置了,API 密钥优先(避免在 shell 中为其他工具设置 GOOGLE_CLOUD_PROJECT 时产生冲突)。
如果您不确定哪个后端处于活动状态,请从您的 MCP 客户端调用 get_config 以确认所选的后端和输出目录。
可用工具
工具 | 描述 | 类型 |
| 根据文本提示生成图像 | 同步 |
| 使用文本提示编辑现有图像 | 同步 |
| 多参考图合成(最多 3 张) | 同步 |
| 根据文本提示生成视频(返回操作 ID) | 异步 |
| 将图像动画化为视频(第一帧) | 异步 |
| 串联视频片段以制作更长内容 | 异步 |
| 检查视频生成进度 | 同步 |
| 下载已完成的视频 | 同步 |
| 根据文本生成口语音频 (TTS) | 同步 |
| 根据文本描述生成 AI 音乐 (Lyria) | 同步 |
| 显示具有功能和定价的可用模型 | 同步 |
| 显示当前后端和配置 | 同步 |
异步工具会立即返回操作 ID。使用 video_status 轮询完成情况,然后使用 download_video 获取文件。
模型层级
图像
层级 | 模型 | 适用场景 | 成本 |
nb2 (默认) |
| 快速迭代,大多数任务 | ~$0.067/张 |
pro |
| 最终渲染,复杂场景 | ~$0.134/张 |
两个层级均支持 1K、2K、4K 分辨率以及 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 的宽高比。
视频
层级 | 模型 | 适用场景 | 成本 |
lite (默认) |
| 大批量,草稿 | $0.05/秒 (720p), $0.08/秒 (1080p) |
fast |
| 高质量迭代 | $0.15/秒 (720p/1080p), $0.35/秒 (4k) |
standard |
| 最终渲染,4K | $0.40/秒 (720p/1080p), $0.60/秒 (4k) |
支持的宽高比为 16:9 和 9:16。支持的持续时间为 4、6 和 8 秒。Lite 支持 720p 和 1080p。Fast 和 Standard 支持 720p、1080p 和 4K。视频扩展 (extend_video) 仅在 Fast 和 Standard 层级可用,且扩展层级必须与原始生成层级匹配。
音频 (TTS)
层级 | 模型 | 适用场景 | 成本 |
tts |
| 具有自然语音的文本转语音 | 标准 Gemini Token 定价 |
generate_audio 工具将文本转换为口语音频。它支持:
语音选择 -- 从预构建的语音中选择,如
Aoede、Kore、Puck等。默认:Aoede语言 -- 设置语言代码(例如
en-US、it-IT、cs-CZ、de-DE)。默认:en-US自然语音 -- 生成具有适当节奏和语调的富有表现力的自然语音
输出保存为原始 PCM 音频 (audio/L16,24kHz 采样率)。该文件可以使用 ffplay 等工具播放,或转换为其他格式:
# Play directly
ffplay -f s16le -ar 24000 -ac 1 ~/generated_media/audio-2026-04-02T12-20-12-0603.pcm
# Convert to WAV
ffmpeg -f s16le -ar 24000 -ac 1 -i audio.pcm audio.wav
# Convert to MP3
ffmpeg -f s16le -ar 24000 -ac 1 -i audio.pcm audio.mp3音乐 (Lyria)
层级 | 模型 | 输出 | 适用场景 | 成本 |
clip (默认) |
| 30 秒片段 | 快速迭代,声音设计 | ~$0.08/首 |
full |
| 最长约 3 分钟 | 带有人声、主歌、副歌的完整歌曲 | 基于 Token |
generate_music 工具根据文本描述创建 AI 生成的音乐。功能包括:
流派和风格 -- 指定任何流派、乐器、BPM、调式/音阶、情绪
结构控制 -- 使用标签如
[Verse]、[Chorus]、[Bridge]、[Intro]、[Outro]自定义歌词 -- 为人声轨道包含带有部分标记的歌词
时间戳控制 --
[0:00 - 0:10] Intro: gentle piano...用于精确的部分计时多语言 -- 提示词语言决定输出语言
高保真 -- 48kHz 立体声 MP3 输出
所有生成的音乐都带有 SynthID 水印。
提示词示例:
# Instrumental
"A gentle acoustic guitar melody in C major, 90 BPM, calm and peaceful indie folk"
# With structure
"[Intro] Ambient synth pad, ethereal
[Verse] Lo-fi hip-hop beat, mellow piano chords, vinyl crackle
[Chorus] Uplifting, add strings and gentle drums
[Outro] Fade out with reverb"
# With lyrics
"Upbeat pop song, 120 BPM, major key
[Chorus] We're dancing in the light / Everything feels right / Under stars so bright tonight"您可以直接传递层级名称(lite、fast、standard、nb2、pro、tts、clip、full)或原始模型 ID。
MCP 客户端配置
Claude Code
添加到您的 Claude Code MCP 设置(~/.claude/settings.json 或项目 .mcp.json):
{
"mcpServers": {
"gemini-media": {
"command": "gemini-media-mcp",
"env": {
"GOOGLE_API_KEY": "your-api-key",
"MEDIA_OUTPUT_DIR": "/path/to/output"
}
}
}
}在上面的 env 块中使用 GOOGLE_API_KEY 或 GEMINI_API_KEY;两者均可接受。
或者,如果是从源代码构建:
{
"mcpServers": {
"gemini-media": {
"command": "/path/to/gemini-media-mcp",
"env": {
"GOOGLE_API_KEY": "your-api-key"
}
}
}
}Claude Code 的配套技能
skills/ 目录包含 Claude Code 技能,这些技能在 MCP 工具之上提供了交互式工作流。每项技能都会引导 Claude 完成特定媒体类型的提示工程、模型选择和迭代优化。
技能 | 目录 | 描述 |
gemini-image-gen |
| 图像生成、编辑和多参考图合成 |
video-gen |
| 带有异步轮询、图生视频、扩展的视频生成 |
music-gen |
| 带有结构标签、歌词、流派控制的音乐生成 |
tts-gen |
| 带有语音和语言选择的文本转语音 |
要安装技能,请将其目录复制到 ~/.claude/skills/:
cp -r skills/video-gen ~/.claude/skills/
cp -r skills/music-gen ~/.claude/skills/
cp -r skills/tts-gen ~/.claude/skills/
cp -r skills/gemini-image-gen ~/.claude/skills/技能是可选的 —— MCP 工具无需它们即可工作。但技能增加了提示工程指导、模型层级建议和交互式审查工作流,可显著提高输出质量。
从源代码构建
git clone https://github.com/mordor-forge/gemini-media-mcp.git
cd gemini-media-mcp
go build ./cmd/gemini-media-mcp/二进制文件将在 ./gemini-media-mcp 创建。
运行测试:
go test ./...贡献
Fork 仓库
创建功能分支 (
git checkout -b feature/your-feature)进行更改并添加测试
运行
go test ./...和go vet ./...提交更改
针对
main分支发起 Pull Request
许可证
Available Tools
14 toolsedit_imageEdit imageA
Change an existing image with an instruction (add/remove/replace elements, restyle, relight, change aspect ratio, fix text) while keeping everything else. Accepts extra reference images to insert or match. Say what must stay unchanged. Saves a new file; the original is kept.
Inputs: image (required), prompt (required), model, imageSize, +4 more. Returns: cost, text, files, model, +2 more
edit_videoEdit videoA
Change an existing clip with an instruction (add, remove or replace objects, restyle, relight, change the background) with Gemini Omni Flash, keeping everything else. Pass the jobId of a finished clip (Omni clips are edited in conversation) or a video file of at most 10 s. Asynchronous like generate_video; about $0.10 per second of video at 720p.
Inputs: prompt (required), jobId, model, video, +5 more. Returns: cost, next, error, files, +6 more
estimate_costEstimate costARead-onlyIdempotent
Estimate the cost of an image, video, speech or music request before running it, optionally comparing all models; also reports remaining budget and whether approval is needed.
Inputs: mediaType (required), text, count, model, +6 more. Returns: note, model, estimate, warnings, +4 more
extend_videoExtend videoA
Continue a completed clip from its end: omni adds up to 10 s (40 s total, keeping characters and audio coherent); Veo fast/standard add about 7 s (720p, up to 148 s, within 2 days). Asynchronous like generate_video.
Inputs: jobId (required), prompt (required), seed, outputName, +3 more. Returns: cost, next, error, files, +6 more
generate_imageGenerate imageA
Create images from a text prompt, optionally guided by up to 14 reference images (subjects, products, style). Default model nb2 (Nano Banana 2.1, $0.04 per 1K image); pro for the densest scenes and final renders ($0.15); nb2-lite for bulk drafts. Returns saved files with URIs you can pass to edit_image, generate_video (image) or other tools.
Inputs: prompt (required), count, model, imageSize, +5 more. Returns: cost, text, files, model, +2 more
generate_musicGenerate musicA
Compose music with Lyria: 30-second clips (clip, $0.04) or full songs of a few minutes with vocals and lyrics (full, $0.08). Control genre, mood, instruments, tempo and structure in the prompt; returns lyrics/structure text when available.
Inputs: prompt (required), bpm, model, format, +6 more. Returns: cost, file, model, lyrics, +2 more
generate_speechGenerate speechA
Turn text into natural speech (WAV) with one voice, or a dialogue between two speakers. Control delivery with style. About $0.01-0.02 per minute of audio. For podcasts, voiceovers, narration and dialogue.
Inputs: text, model, style, voice, +6 more. Returns: cost, file, model, voices, +2 more
generate_videoGenerate videoA
Start a video clip with native audio from a text prompt, optionally from a first frame, first+last frames, or reference images. Default omni (Gemini Omni Flash: 3-10s, cheap 360p drafts up to 4K, up to 10 references). On Vertex AI the default is Veo lite; fast/standard add Veo 4K and ingredients. Veo is leaving the Gemini API (list_models has the date). estimate_cost prices any option. Asynchronous: returns a jobId; then call get_video.
Inputs: prompt (required), seed, image, model, +11 more. Returns: cost, next, error, files, +6 more
get_configGet configurationARead-onlyIdempotent
Show the active backend and how it was chosen, output directory, default models, budgets, input-file policy and configuration warnings. Use it to troubleshoot credentials or missing files.
Returns: budget, backend, project, version, +15 more
get_usageGet usage and spendARead-onlyIdempotent
Report estimated spend for this session, today, this month or all time, broken down by model and tool, with budget remaining, recent calls and running video jobs.
Inputs: period, recent. Returns: note, extra, budget, period, +3 more
get_videoGet video jobAIdempotent
Check a video job and wait for it (default up to 45s). When the job completes, the video is downloaded and returned; calling again is safe and returns the same files.
Inputs: jobId (required), waitSeconds. Returns: cost, next, error, files, +6 more
list_modelsList modelsARead-onlyIdempotent
List current models per media type with aliases, status (GA/preview/deprecated), prices and a short guide to when to use each. detail: true adds supported aspect ratios, sizes, durations and voices; live: true checks what your API key can actually call.
Inputs: live, detail, mediaType, includeInactive. Returns: models, backend, warnings, uncatalogued, +1 more
stitch_tilesStitch upscaled tilesA
Upscale step 3: align each edited tile from tile_image with the image, match its broad color, blend the overlaps and save one large PNG (default 8192 px long edge). Free and local. Reports tiles it rejected (their area keeps the prior pixels) and returns a preview plus 100% crops of the seams to inspect.
Inputs: job (required), tiles (required), details, feather, +2 more. Returns: file, next, pass, tiles, +5 more
tile_imageTile image for upscalingA
Upscale step 1: cut an image into crops shaped to the edit model's aspect ratios. longEdge sets the target (1K-16K, default 8K); with grid and imageSize omitted it picks the cheapest plan that covers it (one tile up to about 4K, a 2x2-4x4 grid beyond). regions re-render faces or text in a later pass. Free and local; reports the edit cost. Step 2: edit_image each crop as the result says. Step 3: stitch_tiles. Detail is invented, not recovered.
Inputs: image (required), grid, model, padding, +5 more. Returns: job, cost, grid, mode, +12 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools have distinct resource+action purposes (generate vs edit vs extend for each media type; tile/stitch form a clear two-step pipeline). A few boundaries are softer: estimate_cost vs get_usage both report spend, and get_config vs list_models both expose backend/model info, but descriptions differentiate them adequately.
All 14 tools follow a strict snake_case verb_noun pattern (generate_image, edit_video, extend_video, get_video, list_models, stitch_tiles). No mixing of camelCase or inconsistent verb styles.
14 tools is well-scoped for a multi-media generation server covering image, video, speech and music plus cost/utilization helpers. Each tool occupies a distinct slot in the lifecycle rather than duplicating capability.
The surface covers generation, editing, extension, upscaling and cost/usage introspection across all four media types, with async job polling handled via get_video. Minor gaps remain, e.g. no explicit audio-video muxing or file management operations, but core workflows have no dead ends.
Maintenance
Related MCP Connectors
MCP server for Google Veo AI video generation
Generate images and videos with Seedance, Veo, Wan, Grok, GPT-Image and Nano Banana via one MCP.
AI image, video, voice and music generation over MCP, routed to Veo 3.1, Seedance 2.5 and more.
MCP server for Qwen Image 3 AI image generation
Related MCP Servers
- AlicenseAqualityBmaintenanceAI 3D model generation and post-processing MCP server — text/image/multiview-to-3D via Tripo, retopology, format conversion (GLB/FBX/OBJ/STL/USDZ), and stylization. Single Go binary, 10 tools.285Apache 2.0
- AlicenseNot gradedqualityBmaintenanceMCP server for generating images and videos using Google Gemini and VEO models, with support for multiple AI models and credential modes.177 PyPI1Apache 2.0
- AlicenseAqualityFmaintenanceProduction-grade MCP server for image and video understanding and generation across Gemini, OpenAI, and Grok.587 PyPI4Apache 2.0
- AlicenseBqualityDmaintenanceA production-ready MCP server that enables Claude and other LLMs to generate images and videos using Google's Gemini AI models (Gemini 2.0 Flash and Veo 2.0).33ISC