MCP Gemini Tts

Gemini TTS MCP服务器

一个模型上下文协议（MCP）服务器，使用Google的GeminiTTS API提供文本到速度的功能。

特性

• 单扬声器TTS：使用30个可用语音生成语音
• 自动分块：通过在句子边界处拆分为逻辑片段来处理长文本
• 多扬声器支持：为每个演讲者创建不同声音的对话
• 自动播放：使用Windows Media Player播放音频
• 文件保存：永久保存音频文件的可选参数
• 临时文件管理：自动清理生成的音频文件
• 基于环境的API密钥：通过环境变量实现安全的API密钥管理

先决条件

必需

• Python 3.10或更高版本：FastMCP和异步功能需要
• Google API密钥：必须访问Gemini API（特别是 gemini-2.5-flash-preview-tts 型号）
• Windows 11：需要通过PowerShell播放音频 System.Media.SoundPlayer
• PowerShell 5.1或更高版本：内置于Windows 11中，用于音频播放

可选的

• MCP客户端：例如Claude Desktop，通过模型上下文协议与服务器交互
• 音频输出设备：用于音频播放测试的扬声器或耳机

API访问要求

• 启用计费的活动Google Cloud帐户
• Gemini API访问（预览期间可能需要等待列表批准）
• 启用TTS权限的API密钥

安装

步骤1：克隆存储库

git clone 
cd mcp-gemini-tts

步骤2：安装依赖项

# Install required packages
pip install -r requirements.txt

验证安装：

# Check Python version (should be 3.10+)
python --version

# Verify FastMCP is installed
python -c "import mcp; print('FastMCP installed successfully')"

步骤3：配置API密钥

选项A：用户环境变量（推荐）

# Set for current user (persists across sessions)
[System.Environment]::SetEnvironmentVariable('GOOGLE_API_KEY', 'your-api-key-here', 'User')

# Restart PowerShell to apply changes

选项B：会话环境变量（临时）

# Set for current session only
$env:GOOGLE_API_KEY = "your-api-key-here"

验证是否设置了API密钥：

# Check environment variable
echo $env:GOOGLE_API_KEY

步骤4：测试安装

# Test the server can start (Ctrl+C to stop)
python src/server.py

# Run example scripts to verify functionality
python src/examples/test_playback.py

预期产量： 服务器应无错误启动，测试脚本应生成并播放音频。

配置

MCP客户端设置

要将此服务器与Claude Desktop或其他MCP客户端一起使用，请配置MCP设置文件。

Claude桌面配置位置：

• 窗户： %APPDATA%\Claude\claude_desktop_config.json

配置：

{
  "mcpServers": {
    "gemini-tts": {
      "command": "python",
      "args": [
        "C:\\Projects\\mcp-gemini-tts\\src\\server.py"
      ],
      "env": {
        "GOOGLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

重要提示：

• 替换 C:\\Projects\\mcp-gemini-tts\\src\\server.py 使用您的实际安装路径
• 使用双反睫毛(\\)在JSON的Windows路径中
• 替换 your-api-key-here 使用实际的Google API密钥
• 修改配置文件后重新启动Claude Desktop

验证配置：

1. 重新启动克劳德桌面
2. 检查一下 gemini-tts 工具出现在可用工具列表中
3. 使用一个简单的命令进行测试：“使用Kore语音生成说‘Test’的语音”

替代方案：直接服务器使用

您也可以在没有MCP客户端的情况下直接运行服务器：

# Start the MCP server (communicates via stdio)
python src/server.py

# Or use the example scripts for direct testing
python src/examples/test_playback.py
python src/examples/test_chunking.py

可用工具

1.生成语音

使用单个语音从文本生成和播放语音。自动将长文本（>3900字节）分块为逻辑片段。

参数：

• text （必填）：要转换为语音的文本（如果>3900字节，则自动分块）
• voice （可选）：语音名称（默认：“Kore”）
• play （可选）：生成后是否播放音频（默认：true）
• save_file （可选）：保存音频的文件路径（例如“output.wav”）

例子：

{
  "text": "Hello, this is a test of the Gemini TTS system!",
  "voice": "Puck",
  "play": true,
  "save_file": "my_audio.wav"
}

长文本示例：

{
  "text": "Very long text that exceeds 3900 bytes will be automatically split into chunks at sentence boundaries, then combined into a single audio file...",
  "voice": "Aoede",
  "play": true
}

2.发电机_多扬声器_速度

使用多个扬声器/声音生成和播放语音。注意：多扬声器不支持自动分块-文本必须小于4000字节。

参数：

• text （必填）：要转换的文本（使用扬声器标签，如“爱丽丝：你好！”）。必须小于4000字节。
• speakers （必填）：扬声器配置阵列

- speaker：说话者姓名/标识符 - voice：此扬声器使用的语音

• play （可选）：生成后是否播放音频（默认：true）
• save_file （可选）：保存音频的文件路径（例如“dialogy.wav”）

例子：

{
  "text": "Alice: Hello! How are you? Bob: I'm doing great, thanks!",
  "speakers": [
    {"speaker": "Alice", "voice": "Kore"},
    {"speaker": "Bob", "voice": "Puck"}
  ],
  "play": true,
  "save_file": "conversation.wav"
}

3.列表_可用_语音

列出语音生成的所有可用语音选项。

参数： 无

可用声音

服务器支持30个预构建的语音：

• Kore、Puck、Charon（基本音色）
• Kore-F、Puck-F、Charon-F（雌性变体）
• Kore-M、Puck-M、Charon-M（雄性变种）
• Aoede、Arcas、Fenrir（专业配音）
• 区域变体：-G、-H、-I、-J、-K、-L后缀

使用 list_available_voices 工具查看完整列表。

技术细节

• 模型: gemini-2.5-flash-preview-tts
• 音频格式：PCM WAV，24kHz，单声道，16位
• API：Google Gemini API通过 google-genai 开发包
• MCP框架：使用FastMCP（Python MCP实现）
• 回放：通过PowerShell安装Windows Media Player System.Media.SoundPlayer

API限制

文本输入限制

字符计数与字节计数

• API限值：每个文本字段4000字节（非字符）
• UTF-8编码：多字节字符（表情符号、非ASCII）消耗的字节数多于字符数
• 示例：“你好👋“=10个字节（5个字符+4个字节表情符号+空格），而不是7个字符

单扬声器模式

• 每次请求的最大值：4000字节（API硬限制）
• 建议块大小：3900字节（100字节安全缓冲区）
• 自动分块：默认情况下，对于大于3900字节的文本启用
• 块状边界：句子结尾处出现切分(., !, ?, \n)保持自然停顿
• 最大组合长度：约25000个字符（约27000个字节，7个块）

多扬声器模式

• 最大文本长度：4000字节（不支持分块）
• 发言者人数：恰好需要2个扬声器（API限制，而不是1个或3个以上）
• 文本格式：必须使用说话者标签（例如，“爱丽丝：你好！鲍勃：你好！”）
• 语音分配：每位演讲者必须有不同的声音 MULTI_SPEAKER_VOICES 列表

常见边缘案例

❌ Multi-speaker with 1 speaker → API Error
❌ Multi-speaker with 3+ speakers → API Error
❌ Multi-speaker with 5000 bytes → Validation Error
❌ Single-speaker with emoji-heavy text → May hit byte limit unexpectedly
✅ Single-speaker with 10,000 bytes → Auto-chunks into 3 segments
✅ Multi-speaker with 3,500 bytes, 2 speakers → Works perfectly

音频持续时间限制

每块持续时间上限

• 每个API调用的最大音频：约5分27秒（327秒）
• 无文件记录的限额：这是一个未正式记录的预览阶段限制
• 行为：API在此持续时间内静默地截断音频
• 文本与持续时间比率：大约1800字节=1分钟的音频（因内容而异）

音频与分块相结合

• 最大组合持续时间：约12分钟（720秒）
• 实施：将多个3900字节的块连接成单个WAV文件
• 计算：7个块×~2.2分钟/块=~15分钟理论值（受播放超时限制）
• 实际极限：由于播放超时12分钟，约25000个字符

工期估算示例

Text Length    Chunks    Est. Duration    Chunking?
-----------    ------    -------------    ---------
1,000 bytes    1         ~33 seconds      No
3,900 bytes    1         ~2.2 minutes     No
8,000 bytes    3         ~4.5 minutes     Yes
15,000 bytes   4         ~8.3 minutes     Yes
25,000 bytes   7         ~13.8 minutes    Yes (may timeout)
30,000 bytes   8         ~16.5 minutes    ⚠️ Exceeds timeout

播放超时

超时配置

• 硬限制：720秒（12分钟）
• 依据：平衡可用性和资源管理
• 适用于：PowerShell System.Media.SoundPlayer 仅播放
• 不影响：文件生成（保存的文件可以是任何长度）

超时行为

• 超时时：音频文件保存有手动播放说明
• 错误信息：包括通过Windows Media Player手动播放的文件路径
• 文件清理：超时时跳过以允许手动访问

避免超时

✅ Keep text under 20,000 characters for reliable playback
✅ Use save_file parameter for long content, play manually
✅ Split very long content into multiple generation calls
❌ Attempting 30,000+ characters in single call (will timeout)

语音系统限制

语音列表分离

• 单扬声器声音：30个名字大写的声音(Kore, Puck, Charon等等）
• 多扬声器声音：30种不同的声音，名字小写(kore, puck, charon等等）
• 不可互换的：在多扬声器模式下使用单扬声器语音会导致API错误

验证错误示例

# ❌ Wrong voice case for mode
generate_speech(text="Hello", voice="kore")  # Error: "kore" not in AVAILABLE_VOICES

# ❌ Wrong voice case for multi-speaker
generate_multi_speaker_speech(
    text="A: Hi! B: Hello!",
    speakers=[{"speaker": "A", "voice": "Kore"}]  # Error: "Kore" not in MULTI_SPEAKER_VOICES
)

# ✅ Correct usage
generate_speech(text="Hello", voice="Kore")  # Single-speaker with capital
generate_multi_speaker_speech(
    speakers=[{"speaker": "A", "voice": "kore"}]  # Multi-speaker with lowercase
)

自动分块

对于长度超过3900字节的文本，系统会自动：

1. 句子边界处的切分：智能地按句点、感叹号、问号和换行符对文本进行分组
2. 生成剧集：为每个块创建单独的音频文件（每个3900字节）
3. 无缝连接：将所有块合并到一个WAV文件中
4. 清理干净：连接后删除临时块文件

效率优化：

• 3900字节块 最大化每个API调用，同时保持100字节的安全缓冲区
• 减少API调用 与较小的块大小相比，增加了约11%
• 示例：25000字节的文本=约7个API调用（与较小块的8个调用相比）

示例用例：

Text: 10,000 bytes (3 chunks)
→ Chunk 1: 3,900 bytes (~2.2 min audio)
→ Chunk 2: 3,900 bytes (~2.2 min audio)
→ Chunk 3: 2,200 bytes (~1.2 min audio)
→ Combined: 10,000 bytes (~5.6 min audio)
→ Only 3 API calls

Text: 25,000 characters (~27,000 bytes, 7 chunks)
→ Supports up to 12 minutes of combined audio
→ Only 7 API calls with 3900-byte chunks
→ Automatically managed with intelligent sentence-boundary splitting

操作限制

平台要求

仅限Windows播放

• 音频回放：需要安装PowerShell 5.1的Windows 11+
• 限制：用途 System.Media.SoundPlayer 这是Windows特有的
• 替代：在非Windows平台上，使用 save_file 参数和手动播放
• 文件生成：适用于任何平台（Linux、macOS、Windows）

PowerShell依赖关系

• 播放需要：PowerShell执行策略必须允许脚本执行
• 检查政策: Get-ExecutionPolicy （应该是 RemoteSigned 或 Unrestricted)
• 设置策略: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
• 测试旁路：出于安全原因不建议

性能约束

API费率限制

• API双子星：受Gemini API标准利率限制（因账户等级而异）
• 冲击波：每个区块=1个API调用（例如，7个区块=7个API调用）
• 错误处理：速率限制错误返回429状态，并带有重试指导
• 推荐：添加具有指数回退的重试逻辑，以供生产使用

内存使用

• 音频缓冲：播放前将完整音频加载到内存中
• 分块：在连接过程中临时存储在内存中的每个块
• 大文件：25000个字符的音频（约30MB WAV）需要约100MB的内存开销
• 推荐：监控内存以生成超长音频

文件系统

• 临时文件：在系统临时目录中创建(tempfile.mkstemp())
• 磁盘空间：每个块~3-5MB，拼接后清理干净
• 并发使用：多代同时发电可能会耗尽温度空间
• 清理：成功时自动，崩溃后需要手动清理

已知问题和解决方法

问题：长音频播放超时

• 症状：12分钟后出现“播放超时”错误
• 变通方案：使用 save_file 参数和手动播放
• 修复：将内容拆分为多个较短的版本

问题：API静默截断5:27

• 症状：文本结束前音频中断（无错误）
• 原因：预览阶段未记录的API持续时间限制
• 变通方案：使用自动分块（默认启用）
• 检测：将生成的音频持续时间与预期持续时间进行比较

问题：多字节字符字节计数

• 症状：文本似乎少于4000个字符，但仍无法通过验证
• 原因：表情符号和非ASCII字符占用多个字节
• 变通方案：使用 len(text.encode('utf-8')) 检查实际字节数
• 示例：“你好👋👋👋“=16个字节，不是9个字符

问题：PowerShell窗口闪存

• 症状：PowerShell窗口在播放过程中短暂出现
• 原因：创建用于音频播放的Windows子进程
• 影响：轻微的视觉干扰，不影响功能
• 没有解决方法：基于PowerShell的播放方法固有

问题：音频设备冲突

• 症状：播放失败，显示“设备繁忙”或没有声音
• 原因：另一个仅使用音频设备的应用程序
• 变通方案：关闭其他音频应用程序，使用 save_file 稍后再玩
• 检测：检查Windows混音器的独占模式应用程序

MCP客户端特定限制

Claude桌面集成

• 配置：配置更改后必须重新启动Claude Desktop
• API密钥：会话期间无法更改（需要重新启动）
• 工具发现：启动后可能需要5-10秒
• 并发：一次一代（基于stdio的通信）

标准协议

• 单螺纹：服务器一次处理一个请求
• 无流媒体：音频必须在播放开始前完成
• 大量回应：包含嵌入式音频数据的JSON响应可能很大（>100KB）
• 超时：MCP客户端超时与播放超时分开（查看客户端文档）

安全考虑

API关键风险敞口

• 环境变量：对以同一用户身份运行的所有进程可见
• 配置文件：以明文形式存储API密钥（确保正确的文件权限）
• 推荐：使用用户级环境变量，而不是系统级
• 最佳实践：定期旋转API密钥，从不提交版本控制

临时文件安全

• 文件权限：临时文件继承系统临时目录权限
• 内容曝光：音频文件包含生成的语音（考虑敏感内容）
• 清理：失败的操作可能会留下临时文件（包含生成的音频）
• 推荐：使用 save_file 对敏感内容具有明确的权限

网络安全

• 传输层安全：所有Gemini API调用都使用HTTPS（由SDK强制执行）
• 数据传输：文本发送到Google服务器进行处理
• 隐私：适用谷歌的数据处理条款（审查Gemini API ToS）
• 考虑：避免在未经适当授权的情况下发送个人身份信息或机密信息

用法示例

配置后，您可以通过MCP客户端使用这些工具：

User: Generate speech saying "Welcome to Gemini TTS!" using the Aoede voice
Assistant: [Uses generate_speech tool with text and voice parameters]

文件结构

mcp-gemini-tts/
├── src/
│   ├── gemini_tts.py    # TTS wrapper class
│   └── server.py         # MCP server implementation
├── pyproject.toml        # Project metadata
├── requirements.txt      # Python dependencies
└── README.md            # This file

故障排除

安装和设置问题

问题：ImportError或ModuleNotFoundError

Solution:
1. Verify Python version: python --version (must be 3.10+)
2. Reinstall dependencies: pip install -r requirements.txt
3. Check virtual environment: Ensure you're in the correct venv
4. Try: pip install --upgrade mcp google-genai

问题：“找不到GOOGLE_API_KEY”错误

Solution:
1. Check environment variable: echo $env:GOOGLE_API_KEY
2. Set if missing: [System.Environment]::SetEnvironmentVariable('GOOGLE_API_KEY', 'your-key', 'User')
3. Restart PowerShell/terminal after setting
4. Verify API key is valid at https://aistudio.google.com/app/apikey

问题：Claude Desktop中的“服务器启动失败”

Solution:
1. Check config file path: %APPDATA%\Claude\claude_desktop_config.json
2. Verify absolute path to server.py (use double backslashes)
3. Check Python is in PATH: python --version
4. Review Claude Desktop logs for specific errors
5. Try running server manually: python src/server.py

音频播放问题

问题：播放时没有声音

Solution:
1. Check Windows audio mixer (other apps using audio exclusively?)
2. Test audio device: Right-click speaker icon → Sound settings → Test
3. Verify PowerShell execution: Get-ExecutionPolicy (should be RemoteSigned/Unrestricted)
4. Try manual playback: Use save_file parameter, open in Windows Media Player
5. Check audio service: services.msc → Windows Audio service (should be Running)

问题：“720秒后播放超时”

Solution:
1. Text is too long (>20,000 characters)
2. Use save_file parameter: save_file="output.wav"
3. Play manually after generation
4. Or split into multiple shorter generations
5. File is preserved at path shown in error message

问题：PowerShell窗口在播放过程中闪烁

This is normal behavior:
- Caused by subprocess creation for PowerShell audio player
- Does not affect functionality
- No workaround available (inherent to implementation)

API和生成问题

问题：“文本超过最大长度”错误

Solution:
Single-speaker mode:
- Automatic chunking should handle this
- If error persists, check for multi-byte characters (emoji)
- Calculate bytes: len(text.encode('utf-8'))

Multi-speaker mode:
- No automatic chunking (hard 4,000 byte limit)
- Reduce text length or split into multiple calls
- Check byte count, not character count

问题：文本结束前音频中断（无声截断）

Cause: 5:27 minute API duration limit

Solution:
- Automatic chunking handles this (enabled by default)
- If issue persists, manually split text into smaller segments
- Each segment should be <3,500 bytes for safety

问题：“超出速率限制”（429错误）

Solution:
1. Wait 60 seconds before retrying
2. Reduce chunking (use shorter text)
3. Check account tier limits at Google AI Studio
4. Implement exponential backoff in production code

问题：“无效语音名称”错误

Solution:
Single-speaker: Use capital case (Kore, Puck, Charon)
Multi-speaker: Use lowercase (kore, puck, charon)
List voices: Use list_available_voices tool
Common mistake: Mixing voice cases between modes

MCP客户端问题

问题：工具未出现在Claude Desktop中

Solution:
1. Restart Claude Desktop completely (not just reload)
2. Check config file syntax (valid JSON, double backslashes in paths)
3. Verify server starts: python src/server.py (should show no errors)
4. Check Claude Desktop logs: %APPDATA%\Claude\logs
5. Wait 5-10 seconds after startup for tool discovery

问题：MCP客户端中的“服务器没有响应”

Solution:
1. Check server process is running
2. Verify stdio communication (server uses stdin/stdout)
3. Test server standalone: python src/server.py
4. Review MCP client logs for connection errors
5. Ensure no firewall blocking (though stdio doesn't use network)

平台特定问题

问题：“PowerShell执行策略受限”

Solution:
1. Check policy: Get-ExecutionPolicy
2. Set for current user: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
3. Confirm: Get-ExecutionPolicy (should show RemoteSigned or Unrestricted)
4. If corporate policy prevents: Use save_file, play manually

问题：在macOS或Linux上运行

Audio playback will not work:
- Playback requires Windows-specific System.Media.SoundPlayer
- File generation works on all platforms
- Workaround: Always use save_file parameter, play with system audio player
- Alternative: Modify gemini_tts.py to use platform-specific playback (afplay, mpg123, etc.)

调试模式

启用详细日志记录：

# Add to top of src/server.py
import logging
logging.basicConfig(level=logging.DEBUG)

单独测试组件：

# Test TTS API access
python -c "from src.gemini_tts import GeminiTTS; tts = GeminiTTS(); print('API access OK')"

# Test audio playback
python src/examples/test_playback.py

# Test chunking
python src/examples/test_chunking.py

检查生成的文件：

# View temp directory
echo $env:TEMP
cd $env:TEMP
Get-ChildItem *.wav | Sort-Object LastWriteTime -Descending | Select-Object -First 5

许可证

MIT许可证

贡献

欢迎投稿！请随时提交拉取请求。