gemini-audio-mcp

🎵 Gemini Audio MCP

Gemini Audio MCP 是一款高性能的模型上下文协议（MCP）服务，专为专业级音频合成打造。它利用 Gemini 2.5 多模态 Live API 和 Google DeepMind 的 Lyria 3 模型，按需生成高保真的环境音景、音乐作品和富有表现力的旁白。

---

🛠 前置条件

部署服务前，请确保环境满足以下技术要求：

1. FFmpeg（核心处理引擎）

音频编码、解码和转码所需的高性能工具。

• macOS：brew install ffmpeg
• Windows：winget install ffmpeg 或从 ffmpeg.org 下载。
• Linux（Ubuntu/Debian）：sudo apt update && sudo apt install ffmpeg

2. Rust 工具链（编译）

从源代码构建服务所需。

• 通过 rustup.rs 安装：curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

3. Node.js 和 NPM（运行时）

使用预编译 NPM 包时所需。

• 版本：node >= 18.0.0

---

🚀 安装与部署

全局安装（通过 NPX）

将服务集成到 MCP 客户端（例如 Claude Desktop）的最快方式。

{
  "mcpServers": {
    "gemini-audio": {
      "command": "npx",
      "args": ["-y", "gemini-audio-mcp"],
      "env": {
        "GEMINI_API_KEY": "YOUR_SECURE_API_KEY"
      }
    }
  }
}

手动构建（优化）

如需获得最高性能，可在本地构建 Rust 二进制文件：

1. 克隆并构建：

   git clone https://github.com/mcp-servers/gemini-audio-mcp.git
   cd gemini-audio-mcp
   cargo build --release
   

2. 查找二进制文件：优化后的二进制文件位于 ./target/release/gemini-audio-mcp。

---

🔑 API 密钥管理

此服务需要有效的 Google AI Studio API 密钥。

1. 从 Google AI Studio 获取密钥。
2. 安全最佳实践：切勿将密钥硬编码。通过 GEMINI_API_KEY 环境变量注入密钥。
3. 套餐说明：使用 Lyria 3（Pro/Clip）模型通常需要 付费套餐，或在 Google AI Studio 中拥有特定的预览权限。

---

🎮 工具使用指南

1. 环境音生成（generate_soundscape）

合成沉浸式、无人声的环境音纹理。

{
  "name": "generate_soundscape",
  "arguments": {
    "prompt": "Deep underwater abyss, low-frequency whale songs, rhythmic air bubbles rising, muffled aquatic pressure.",
    "duration": 60,
    "quality": "high",
    "auto_play": true
  }
}

2. 专业音乐（generate_music）

生成结构完整的音乐作品，并可选控制人声。

{
  "name": "generate_music",
  "arguments": {
    "prompt": "Melancholic solo cello in a vast cathedral with 5-second decay reverb.",
    "bpm": 72,
    "song_key": "D minor",
    "intensity": 4
  }
}

3. 富有表现力的语音（generate_voice）

使用 Gemini 2.5 Native Audio 生成旁白和角色对话。

{
  "name": "generate_voice",
  "arguments": {
    "text": "The artifacts are stable, but the rift remains open.",
    "voice_direction": "Gravelly, urgent, whispered"
  }
}

4. 动态演变（transition_soundscape）

对两种不同的环境进行交叉淡化，实现无缝的场景切换。

{
  "name": "transition_soundscape",
  "arguments": {
    "from_prompt": "Quiet library silence.",
    "to_prompt": "Sudden heavy rain on a tin roof.",
    "transition_duration": 8
  }
}

---

⚙️ 高级参数

参数	类型	描述
seed	Integer	确保音频输出具有确定性且可复现。
image_path	String	多模态：使用本地图像引导音响氛围（例如，共鸣效果）。
bpm	Number	显式设置节奏速度（音乐创作必不可少）。
intensity	Number	1-10 的刻度，用于控制动态范围和复杂度。
guidance	Number	0.0-6.0 的刻度，用于控制对提示词的遵循程度（Lyria 模型）。
duration	Number	目标时长（秒）。会触发 无缝循环引擎。

---

🔬 架构概览

Gemini Audio MCP 采用独特的 混合引擎策略：

• WebSocket 循环：连接到 Gemini 2.5 Live，执行低延迟的交互式语音和拟音任务。
• REST 管线：连接到 Lyria 3 Pro，进行高保真音乐合成。
• PCM 处理：基于 Rust 的内部循环（decode -> crossfade -> loop -> encode）可确保将短音频片段转换为无缝、无限延展的音景，且不会出现可听见的咔嗒声。

---

🧪 故障排除

FFmpeg 错误

• “FFmpeg 未找到”：确保 ffmpeg 位于系统 PATH 中。在终端中运行 ffmpeg -version 进行验证。
• 转码失败：检查是否安装了所需的编解码器（例如，用于 MP3 的 libmp3lame）。大多数标准 FFmpeg 安装都包含这些编解码器。

API 问题

• 429 速率限制：服务端通过信号量限制并发数，但请确保你的 API 套餐支持所请求的模型。
• 音频输出为空：确认 GEMINI_API_KEY 正确，并且你的账户有权访问所请求的模型（尤其是 lyria-3-pro-preview）。

---

📄 许可证

采用 MIT License 授权。由 MCP 社区精心打造。