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（项目凭据）

快速开始

# 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 或 GOOGLE_CLOUD_PROJECT 中的一个。如果两者都设置了，API 密钥优先（避免在 shell 中为其他工具设置 GOOGLE_CLOUD_PROJECT 时产生冲突）。

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

可用工具

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

模型层级

图像

两个层级均支持 1K、2K、4K 分辨率以及 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 的宽高比。

视频

支持的宽高比为 16:9 和 9:16。支持的时长为 4、6 和 8 秒。Lite 支持 720p 和 1080p。Fast 和 Standard 支持 720p、1080p 和 4K。视频扩展 (extend_video) 仅在 Fast 和 Standard 层级可用，且扩展层级必须与原始生成层级匹配。

音频 (TTS)

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)

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 完成特定媒体类型的提示词工程、模型选择和迭代优化。

要安装技能，请将其目录复制到 ~/.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