Skip to main content
Glama
gemini-media-mcp

gemini-media-mcp

by mordor-forge

gemini-media-mcp

Go License gemini-media-mcp MCP server

用于通过 Google Gemini API 和 Vertex AI 进行 AI 媒体生成的统一 Go MCP 服务器。

gemini-media-mcp MCP server

功能特性

  • 图像生成 -- 支持可配置宽高比和分辨率(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 客户端配置。

配置

变量

必需

默认值

描述

GOOGLE_API_KEY

是*

--

Gemini API 密钥。也接受 GEMINI_API_KEY

GOOGLE_CLOUD_PROJECT

是*

--

用于 Vertex AI 后端的 GCP 项目 ID

GOOGLE_CLOUD_LOCATION

否

us-central1

Vertex AI 的 GCP 区域

MEDIA_OUTPUT_DIR

否

~/generated_media

保存媒体文件的目录

*必须设置 GOOGLE_API_KEY 或 GOOGLE_CLOUD_PROJECT 中的一个。如果两者都设置了,API 密钥优先(避免在 shell 中为其他工具设置 GOOGLE_CLOUD_PROJECT 时产生冲突)。

如果您不确定哪个后端处于活动状态,请从您的 MCP 客户端调用 get_config 以确认所选的后端和输出目录。

可用工具

工具

描述

类型

generate_image

根据文本提示生成图像

同步

edit_image

使用文本提示编辑现有图像

同步

compose_images

多参考图合成(最多 3 张)

同步

generate_video

根据文本提示生成视频(返回操作 ID)

异步

animate_image

将图像动画化为视频(第一帧)

异步

extend_video

串联视频片段以制作更长内容

异步

video_status

检查视频生成进度

同步

download_video

下载已完成的视频

同步

generate_audio

根据文本生成口语音频 (TTS)

同步

generate_music

根据文本描述生成 AI 音乐 (Lyria)

同步

list_models

显示具有功能和定价的可用模型

同步

get_config

显示当前后端和配置

同步

异步工具会立即返回操作 ID。使用 video_status 轮询完成情况,然后使用 download_video 获取文件。

模型层级

图像

层级

模型

适用场景

成本

nb2 (默认)

gemini-3.1-flash-image-preview

快速迭代,大多数任务

~$0.067/张

pro

gemini-3-pro-image-preview

最终渲染,复杂场景

~$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 (默认)

veo-3.1-lite-generate-preview

大批量,草稿

$0.05/秒 (720p), $0.08/秒 (1080p)

fast

veo-3.1-fast-generate-preview

高质量迭代

$0.15/秒 (720p/1080p), $0.35/秒 (4k)

standard

veo-3.1-generate-preview

最终渲染,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-2.5-flash-preview-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 (默认)

lyria-3-clip-preview

30 秒片段

快速迭代,声音设计

~$0.08/首

full

lyria-3-pro-preview

最长约 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

skills/gemini-image-gen/

图像生成、编辑和多参考图合成

video-gen

skills/video-gen/

带有异步轮询、图生视频、扩展的视频生成

music-gen

skills/music-gen/

带有结构标签、歌词、流派控制的音乐生成

tts-gen

skills/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 ./...

贡献

  1. Fork 仓库

  2. 创建功能分支 (git checkout -b feature/your-feature)

  3. 进行更改并添加测试

  4. 运行 go test ./... 和 go vet ./...

  5. 提交更改

  6. 针对 main 分支发起 Pull Request

许可证

Apache-2.0

Available Tools

14 tools
edit_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 costA
Read-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 configurationA
Read-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 spendA
Read-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 jobA
Idempotent

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 modelsA
Read-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

    A4.1/5.0

    Scored across 14 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers